Skunkware 5/Skunkware 5.iso/src/X11/tclMotif-1.4/doc/userman.tex

Texinfo Document | 1995-06-29 | 146.1 KB | 3,230 lines

\documentstyle[titlepage,makeidx]{article}
\input epsf
\pagestyle{myheadings}
\advance\leftmargin -.3in
\advance\textwidth   .6in
\advance\topmargin  -.3in
\advance\textheight  .6in
\def\titles#1{\markboth{#1}{#1}}
\def\tmVersion{1.0}
\def\note#1{{\sloppy\marginpar{\tiny #1}}
\def\sym#1{{\tt\sl #1\/}}
\def\descriptionlabel#1{\hspace\labelsep #1}
\def\Tcl{{\sl Tcl\/}}
\def\Tk{{\sl Tk\/}}
\def\Tm{{\sl Tm\/}}
\def\moat{{\sl Mo\-at\/}}
\def\Motif{{\sl OSF/\linebreak[0]Mo\-tif\/}}
\def\XWin{{\sl X Window\/}}
\def\XWinsys{{\sl the \XWin\ system\/}}
\def\Xlib{{\sl Xlib\/}}
\def\Xt{{\sl X toolkit\/}}
%---------------------------------------------------------
% Obey \par, even after an item in a description environement :
\def\dopar{
    \mbox{\ }\newline
%---------------------------------------------------------
\def\underscore{\kern.06em\vbox{\hrule width.3em}}
\def\sanetty{%
\catcode35=12% #
\catcode36=12% $
\catcode37=12% %
\catcode38=12% &
\catcode64=12% @
\catcode91=12% [
\catcode93=12% ]
\catcode95=12% _
\def\_{\char 95\protect\linebreak[0]}%
\tt\null}% null just do nothing !
\def\fulltty{\sanetty%
\catcode`\{=12\catcode`\}=12\catcode92=12%
\hyphenpenalty=10000\Spacingspaces\catcode`\|=0}
%---------------------------------------------------------
% Force spaces and tabs to produce horizontal spaces :
\def\obeytabs{\catcode `\^^I=13}
{\obeyspaces\obeytabs
\gdef\Spacingspaces{\obeytabs\obeyspaces
\let \xxspace
\let^^I\xxtab
\def\xxspace{\mbox{\hspace{1.2ex}}}
\def\xxtab{\mbox{\hspace{4.8ex}}}
%---------------------------------------------------------
% Force newlines to start a new paragraph, with some further
% indentation.
\makeatletter
{\catcode`\^^M=13%
    \gdef\Newlines{%
        \catcode`\^^M=13%
        \def^^M{\xxnewline}%
        \ignorespaces\@gobblecr%
{\catcode `\^^I=13
\gdef\ignoretabs{\@ifnextchar    {\@gobble}{\ignorespaces}}
\makeatother
\def\xxnewline{\par\noindent\mbox{\hspace{8ex}}\ignoretabs}
\def\DontIgnoreSpace{
    \def\ignoretabs{}
%---------------------------------------------------------
% The nastiest part: create command to parse Tcl codes, despite
% the collision between Tcl and TeX macro chars.
    \catcode `\|=0  |catcode `|[=1  |catcode `|]=2
    |catcode `|\=12 |catcode `|{=12 |catcode `|}=12
    |catcode `|>=12 |catcode `|<=12 |catcode `|#=11
    |catcode `|%=6
    |gdef|xxtclmode%1\end{tclmode}[%1|end[tclmode]|par]
    |gdef|xxtclmodestar%1\end{tclmode*}[%1|end[tclmode*]|par]
] % This is the matching brace !
%---------------------------------------------------------
% The Tcl mode environment.
% This mode ignore tab/space at begin of line. If you
% want to keep them either use the * variation, or
% add a | from where you want to keep them.
\def\tclmode{
    \begingroup
    \fulltty\Newlines\xxnewline
    \xxtclmode
\let\endtclmode=\endgroup
\makeatletter
\@namedef{tclmode*}{
    \begingroup
    \fulltty\Newlines\DontIgnoreSpace
    \xxtclmodestar
\@namedef{endtclmode*}{\endtclmode}
\makeatother
%---------------------------------------------------------
% Include a file, in Tcl environment.
\def\ttinclude #1{
    \begingroup
    \Newlines\fulltty\DontIgnoreSpace
    \xxnewline
    \input #1
    \endgroup
%---------------------------------------------------------
% Moat command/call back/resource definition.
\def\cmd#1{{\rm\tt #1}}
%---------------------------------------------------------
% Import a EPSF file, and draw a frame around it.
\def\windowdump#1{\fbox{\epsfbox{examples/#1.epsf}}}
\def\window#1{\par
    \begin{center}
        \leavevmode\windowdump{#1} \\
    \end{center}\par
\def\example#1{
    \begin{center}
        (screen display)
    \end{center}
    \ttinclude{examples/#1.tcl}
    \begin{center}
        (the corresponding \moat\ script)
    \end{center}
\def\figureexample#1#2{
    \begin{figure}[htbp]
        \example{#1}
        \caption{#2}
        \label{fig:#1}
    \end{figure}
%---------------------------------------------------------
% Generation transparente (\id[xyz]) ou non (\myindex[xyz]) de
% l'index.
\makeatletter
\def\defx#1{\gdef\@mainidxentry{#1}}
\defx{}
\def\myindexx#1{
    \defx{#1}
    {\sanetty\index{#1@{\tt #1}}}
\def\myindexy#1{
    {\sanetty\index{{\@mainidxentry}@{\tt \@mainidxentry}!{#1}@{\tt #1}}}
\def\idx#1{{\tt #1}\protect\myindexx{#1}}
\def\idy#1{{\tt #1}\protect\myindexy{#1}}
\def\indexeditem#1#2{
    \index{#1@#2}\defx{#2}
    \item[#2] \dopar
\makeindex
%---------------------------------------------------------
\def\co{$^{\mbox{co}}$}
\def\ro{$^{\mbox{ro}}$}
\def\cro{$^{\mbox{cro}}$}
%---------------------------------------------------------
% Define the resource table environement
\def\rsrctable#1{
    % \begin{figure}[htbp]
    \begin{center}
    \label{rsrc:#1}
    \begin{tabular}{lcl}
  \cmd{#1} resource name    & default value & type or legal values \\
  \hline%------------------------------------------------------------
\def\endrsrctable{
    \end{tabular}\end{center}
    % \end{figure}
%---------------------------------------------------------
\begin{document}
\titles{}
\title{    A Tentative User and Reference Manual \\
            for TclMotif \tmVersion
\author{
    Jean-Dominique Gascuel, iMAGIS/IMAG, Grenoble, France \\
    {\tt [e-mail]} \\[2mm]
    Jan Newmarch, University of Canberra, Australia \\
    {\tt [e-mail]} \\[2mm]
\maketitle
%------------------------------------------------------------------------
\section*{Introduction}
\titles{Intro}
TclMotif, alias Tm, is a binding of the \Tcl\ language%
\footnote{
    For more information on \Tcl\  and \Tk, see the very neat book
    written by their author,
    ({\sl An Introduction To Tcl and Tk}, J. Ousterout, Addison-Wesley, 1994)
} to the \Motif\  widgets.
\Tcl\ is an interpreted language originally intended for use as a command
language for other applications. It has been used for that, but has also
become useful as a language in its own right.
\Tcl\ has been extended by a set of widgets called \Tk. The \Tk\ widgets are not
based on the \Xt\ intrinsics, but are built above \Xlib. They allow an easy
way of writing \XWin\  applications.
The standard set of widgets in the X world is now the \Motif\  set. This forms
a large set of widgets, and these have been through a large amount of
development over the last five years. Use of this set is sometimes a
requirement by business, and other widget sets try to conform to them in
appearance and behavior.
Furthermore, you are sometimes faced with toolkits that use \Xt-based widgets.
In this case, you have to
use a \Xt\ compatible interface builder.
\Tm\ allows the programmer to use the \Motif\  widgets instead of the
\Tk\ widgets from \Tcl\  programs. This increases programmer choices, and allows
comparison of the features of both \Tcl\  and the \Tk/\Motif\  style of widget
programming.  The binding gives the usefull subset of the \Motif\ widgets,
accessible through the simple interpreted \Tcl\ language.
%-------------------------------------------------------------------------
\subsection*{Acknowledgments}
\Tm\ is based on \Tk\ for the style of widget programming. This was
because it provides a good model, but it also allows the \Tcl\  programmer to
move relatively easily between \Tk\ and \Motif\  programming. An alternative
style of binding to \Motif\  is used in the WKSH system, which performs a
similar sort of role for the Korn Shell. An intermediate style is provided
by the {\sl Wafe\/} \Xt-based frontend based on \Tcl.
\medskip
As I'm trying to understand \Tm\ in deep, I started to insert my
own notes in the user manual provided by Jan Newmarch.
As time is going, this notes becomes more and more important,
and I decided that they may end-up in a usefull user and reference manual
for \Tm.
They are just my own interpretation of the Scriptures.
%-------------------------
\subsection*{Reading this manual}
The first section, {\em Getting Started}, might be sufficient for programmers
very familiar both with \Motif\ and \Tcl.
\Tcl\ beginners should start by reading the Ousterout book defining
Tcl~7.
\medskip
The second part, starting at section 2~{\em Basics}, is a description
of all the basics \Motif\ concepts, intented for \Motif\ beginners.
\medskip
The last part of this manual, starting from section~\ref{sec:abstracts}
have been written to be a full reference manual of \Tm, with meaningfull
examples, all supported resources, default values, ...
\medskip
Finally, the {\bf index} page~\pageref{index} should provide an extensive
and easy crossreference of all supported features.
%-------------------------------------------------------------------------
\section{Getting Started}
\titles{Getting Started}
\Tcl/\Motif\  programs may be run by the \moat\ (MOtif And \Tcl) interpreter.
When called with no arguments it reads \Tcl\ commands from standard input.
\noindent
When called by
\begin{center}
    \cmd{moat file-name}
\end{center}
it reads \Tcl\ commands from \cmd{file-name}, executes them and then enters the
\moat\ event loop.  This is similar to the \Tk\ `wish' and the concept was
borrowed from there.
Depending on your shell interpreter, you will probably be able to run
\Tcl -- \Motif\  programs as stand alone programs. If your \moat\ interpreter is
installed in \cmd{/usr/local},
make this the first line of your executable program~:
\begin{tclmode}
    #!/usr/local/bin/moat
\end{tclmode}
%----------------------------
\subsection{A simple example}
\titles{A simple example}
The following example is in the programs directory as \cmd{progEG}.
The typical structure of a \Motif\ program is that the top-level object is a
mainWindow. This holds a menu bar, and a container object such as a form or
a rowColumn which in turn holds the rest of the application objects. So a
mainWindow with a list and some buttons in a form would be created by
\begin{tclmode}
    xtAppInitialize -class Example
    xmMainWindow .main
    xmForm .main.form
    xmList .main.form.list
    xmPushButton .main.form.btn1
    xmPushButton .main.form.btn2
\end{tclmode}
The \cmd{xmForm} acts as what is called the ``workWindow'' of the mainWindow.
This resource would be set by
\begin{tclmode}
    .main setValues -workWindow .main.form
\end{tclmode}
\noindent
Values would also be set into the list and buttons:
\begin{tclmode}
    .main.form.list setValues \
        -itemCount 3 \
        -items "one, two, three" \
        -selectionPolicy single_select
    .main.form.btn1 setValues -labelString Quit
    .main.form.btn2 setValues -labelString "Do nothing"
\end{tclmode}
\noindent
Geometry would be set for the form, to put the objects in their correct
relation to each other. Suppose this is the list on the left, with the two
buttons one under the other on the right:
\begin{tclmode}
    .main.form.list setValues \
        -topAttachment attach_form \
        -leftAttachment attach_form \
        -bottomAttachment attach_form
    .main.form.btn1 setValues \
        -topAttachment attach_form \
        -leftAttachment attach_widget \
        -leftWidget .main.form.list
    .main.form.btn2 setValues \
        -topAttachment attach_widget \
        -topWidget .main.form.btn1 \
        -leftAttachment attach_widget \
        -leftWidget .main.form.list
\end{tclmode}
\noindent
Once evrything has been correctly setup, we can tell \Motif\ to
manage all the widgets, so that they will be shown on screen~:
\begin{tclmode}
    .main manageChild
    .main.form manageChild
    .main.form.list manageChild
    .main.form.btn1 manageChild
    .main.form.btn2 manageChild
\end{tclmode}
\noindent
The behaviour of our application would be set by callback functions~:
\begin{tclmode}
    .main.form.btn1 activateCallback {exit 0}
    .main.form.list singleSelectionCallback {
        puts stdout "Selected %item"
\end{tclmode}
\noindent
And finally, windows are created and the main event loop is entered:
\begin{tclmode}
    . realizeWidget
    . mainLoop
\end{tclmode}
\noindent
Once entered in the main event loop, the application is really running :
widgets are created, displayed, and manipulated accordingly to user events
that trigger the associated callbacks.
%-----------------------------
\subsection{What next ?}
{\em Thou shall read this manual !}
\medskip
\Tm\ resource names stick to usual \Motif\ name with a leading {\tt -} replacing
the {\tt XmN} prefix.
The \Tm\ constants are specified by their \Motif\ name,
without the {\tt Xm\_} prefix, either in upper
or lower case.
%-------------------------------------------------------------------------
\section{Basics}
\titles{Basics}
\Motif\ use a hierarchy of sub-windows to create interface elements,
such as menu item, push button or text entry fields.
In the \Xt\  and \Motif\  jargon, they are called ``widgets''%
\footnote{
    Widget stands for window objects.
Widgets are just those visual objects that can be seen on the screen,
or interacted width by the mouse or keyboard.
They are organized in a hierarchy, with the application itself
forming the its root.
Programming a graphic user interface mainly consists of the following
steps~:
\begin{itemize}
    \item
        Creating all the widgets you needs, in a suitable hierarchy.
    \item
        Configuring colors, sizes, alignments, fonts, ...
        In \Motif, widget get their configuration options
        from so called resources.
        These resources may be set on a per widget basis
        or on a per widget class basis
        (e.g. "all push buttons should have red background").
        Furthermore, \Motif\  provides inheritance between
        widget classes (for instance, push button have a background color
        resource, because they  inherit its existance (but not its value) from Label,
        which inherits it from Primitive, which inherits it from Core).
        Usually, applications provide defaults resources for
        widget classes,
        and each user modify some of them on a per session basis
        (file \cmd{\~/.Xdefaults}).
    \item
        Programming your interface to react to user inputs~:
        what function should be called when the save button is pushed ?
        In \Motif\  jargon, you add ``callbacks'' to widgets.
        A call back is a fragment of \Tcl\  code which is executed on
        a dedicated event (for instance,
        execute \cmd{\{puts stdout "Hello World"\}} when the mouse
        button 1 is released over the ``push~me" button).
\end{itemize}
The following sections will detail all this concepts.
\subsection{Widget Names}
    \index{widget path names}
\Tcl\ is a string based language (the only data type is string),
and widget are organized in a hierarchical structure.
To accommodate this, the naming of objects within this
hierarchy is similar to the ``absolute
path names'' of Unix files with a `{\tt .}' replacing
the `{\tt /}' of Unix.
The application itself is known as `{\tt .}'.
A Form in the application may be known as `{\tt .form1}'.
A Label in this form may be `{\tt .form1.okLabel}', and so on.
Note that \Xt\ requires that `{\tt .}' can only have one child
(except for dialogs, which are not mapped inside their parents).
This naming convention is the same as in \Tk.
\subsection{Widget creation commands}
Widgets belong to classes, such as Label, xmPushButton or
List.  For each class there is a creation command which
takes the pathname of the object as first argument with
optional further arguments:
\begin{center}
    \sym{creationCommand} \sym{widgetName} ?\cmd{managed}? \sym{resourceList}
\end{center}
\noindent where~:
\begin{description}
    \item[\sym{creationCommand}] \dopar
        is the class of the widget your are creating.
        Basically, all the \Motif\
            \cmd{Xm\-Create\-SomeWidget()}
        calls should be binded to a \cmd{xmSomeWidget}
        \moat\ command.
        The extensive list of currently supported creation command
        is given below.
    \item[\sym{widgetName}]\dopar
        the full path name of the new widget. Note that
        this specify both the parent widget (which
        should already exists), and the name of the new
        child.
    \item[\cmd{managed}]\dopar
        Before a widget can be displayed, it must be brought under
        the geometry control of its parent (similar to placing a \Tk\ widget).
        This can be done by the \cmd{manageChild} widget method,
        or by using the \idx{managed} argument at creation time.
        If present, this option should be the first one.
        A widget might be managed but unmaped, in which case it is
        invisible (see \cmd{-mapedWhenManaged}, page~\pageref{rsrc:Core}).
        The main use of ``not yet managed widget" are menus
        (when they are not visible),
        and sub-widgets which will resize to an unknown
        dimension at the time of creation of their parents.
    \item[\sym{resourceList}]\dopar
        An optional succession of resource name/ string\_value pairs.
\end{description}
\noindent For instance :
\begin{tclmode}
    xmForm  .form1 managed
    xmLabel .form1.okLabel managed
    xmPushButton .form1.cancelButton managed \
        -labelString "Get rid of me"
\end{tclmode}
\noindent
creates a Form \cmd{form1} as child of `\cmd{.}', a label
\cmd{okLabel} and a push button \cmd{cancelButton} as children of \cmd{form1}.
The \cmd{cancelButton} has additional arguments that set the
labelString to ``Get rid of me".
The set of classes generally mirrors the \Motif\  set.
Some widgets in \Motif\ and \Xt\ are not accessible from
this binding because they are intended for use in
inheritance only, such as Core, Shell and Primitive.
Gadgets, a \Motif\ variation of widgets, designed to cope with
early very slow X window server is not supported too, because
are not needed any more.
\medskip
The following basic widget will be detailed in section
\ref{sec:basic}~:
\begin{center} \begin{tabular}{ll|ll}
    \hline%-------------------------------------------------
    \cmd{xmPushButton}     & a simple button,        &    \cmd{xmLabel}         & a fixed piece of text \\
    \cmd{xmArrowButton} & with an arrow face,    &    \cmd{xmTextField}    & one line text editor \\
    \cmd{xmToggleButton}& with an on/off box,    &    \cmd{xmText}         & a full text editor \\
    \cmd{xmDrawnButton} & with user graphics,    &    \cmd{xmList}         & a list selector, \\
    \cmd{xmFrame}         & a 3-D border,            &    \cmd{xmScale}         & a slider on a scale \\
    \cmd{xmSeparator}     & a simple line,        &    \cmd{xmScrollBar}    & horizontal or vertical \\
    \hline%-------------------------------------------------
\end{tabular} \end{center}
Manager widgets are used to layout several widgets together.
Placing widgets inside widgets enable to create hierarchies suitable
for complex user interface design.
Section \ref{sec:managers} will discuss the following manager
widgets~:
\begin{center} \begin{tabular}{ll}
    \hline%-------------------------------------------------
    \cmd{xmBulletinBoard}     & simple x,y layout, \\
    \cmd{xmForm}             & layout widgets with realtional constraints, \\
    \cmd{xmRowColumn}         & for regular geometry management, \\
    \cmd{xmPanedWindow}     & multiple panes separated by sashes \\
    \hline%-------------------------------------------------
\end{tabular} \end{center}
Section \ref{sec:menus} present special widgets to build menus.
They may contain any flavor of button, separator, or other
widgets, in addition to the following~:
\begin{center} \begin{tabular}{ll}
    \hline%-------------------------------------------------
    \cmd{xmMenuBar}        & a row-Column used to create an horizontal menu. \\
    \cmd{xmPulldownMenu}    & a row-Column used to create a vertical menu. \\
    \cmd{xmPopupMenu}        & a menu on its own (transient) window. \\
    \cmd{xmCascadeButton} & a special pushbutton to call a sub-menu. \\
    \hline%-------------------------------------------------
\end{tabular} \end{center}
\Motif\ provides the following more complicated widgets.
They are composed of several graphic entity, but nearly alway appear
as a unique widget.
Their \moat\  binding will be detailed in section \ref{sec:complex}
\begin{center} \begin{tabular}{ll}
    \hline%-------------------------------------------------
    \cmd{xmScrolledWindow}     & for displaying a clip view over another widget, \\
    \cmd{xmScrolledList}     & a partial view of a list, \\
    \cmd{xmScrolledText}     & a partial view of a text, \\
    \cmd{xmMainWindow}        & contains the main application windows, a menu bar, ... \\
    \cmd{xmCommand}         & a command entry area with a history list, \\
    \cmd{xmMessageBox}         & message display area on its own window, \\
    \cmd{xmSelectionBox}    & A list to select from. \\
    \cmd{xmFileSelectionBox} & selection of a file from a list. \\
    \hline%-------------------------------------------------
\end{tabular}\end{center}
\Motif\ also has convenience functions to create
dialogs.  These don't create ordinary widgets, but
\Motif\ pretends that they do.
They appear in their own (transient) window, and have
push buttons at the bottom line (Ok/Cancel/...).
\moat\ follows this, and the following dialogs will be described
in section \ref{sec:Dialogs}.
\begin{center}\begin{tabular}{ll}
    \hline%-------------------------------------------------
    \cmd{xmBulletinBoardDialog} & a dialog with arbitrary contents. \\
    \cmd{xmFormDialog}            & a dialog based on form \\
    \cmd{xmMessageDialog}       & a dialog showing a message \\
    \cmd{xmInformationDialog}   & a dialog displaying information \\
    \cmd{xmPromptDialog}        & a dialog with a prompt area \\
    \cmd{xmQuestionDialog}      & a dialog asking a question \\
    \cmd{xmWarningDialog}       & a dialog showing a warning \\
    \cmd{xmWorkingDialog}       & a dialog showing a busy working message \\
    \cmd{xmSelectionBoxDialog}  & a dialog based on xmSelectionBox \\
    \cmd{xmFileSelectionDialog} & a dialog based on xmFileSelectionBox \\
    \hline%-------------------------------------------------
\end{tabular}\end{center}
When you have to destroy such widgets, you must destroy the
real dialog widget, that is to say the parent of the usually
manipulated widget~:
\begin{tclmode}
    xmQuestionDialog .askMe managed
    [.askMe parent] destroyWidget
\end{tclmode}
\subsection{Widget methods}
\label{sec:wcmd}
    \index{widget methods}
Creating a widget actually creates a \Tcl\  command known by its
path name.
This command should be executed with at least one parameter to
either change the behavior of the object or the value of its
components, or to get information about the object.
The first parameter acts like a ``method'' to the object, and
specifies an action that it should perform.
The general syntax is~:
    \begin{center}
        \sym{targetWidgetName} \hspace{2mm}
        \sym{widgetCommand} \hspace{2mm}
        \sym{?options?}
    \end{center}
as in the following examples~:
\begin{tclmode}
    .root.label manageChild
    .root setValues -title "Hello world"
\end{tclmode}
\Motif\ uses the concept of inheritance for resources (see
section~\ref{sec:resources}) and translations (see
section~\ref{sec:translations}).
\moat\ extend this to methods, which call \Motif\
function on the target widget.
\subsection{Widget resources}
In \Motif\ jargon ``resources'' are variables shared between
the widgets and the application.
Their default value enable to easily handle common look and
deal across application.
They are also used to communicate information between the
application and the interface.
Section \ref{sec:resources} will describe resource concepts,
default value policy and types.
A set of resources, common to many widget, will be described in
section~\ref{sec:abstracts}.
\subsection{Widget actions and callbacks}
A user interface have to react to user inputs such as a mouse
click, or a key stroke.
As a particular user input may takes effects both on the interface
and on the application, the reactions may be of two kinds~:
\begin{description}
    \item[\bf Actions:] \dopar
        are behavior internal to \Motif that manage the interface.
    \item[\bf Callbacks:] \dopar
        are defined by the application. They are used to trigger
        application's responses to user input.
\end{description}
Each widget class may define a set of Actions and Callbacks.
\medskip
Section~\ref{sec:actions} deals with actions and translations,
section~\ref{sec:callbacks} will present the main callback concepts,
and section~\ref{sec:abstracts} the set of actions and callbacks
common to many supported \moat\ widgets.
\subsection{Translations}
In \Motif, reaction to user input are defined from a high level
point of view~: basic actions includes arming a button, selecting
a list item, setting input focus to a particular widget.
On the other hand, basic events are mouse clicks,
keystroke and modifier key state, etc. when the mouse is
over some widget.
\Motif use ``translations'' table to bind the later to the
former.
\subsection{The root widget}
In earlier versions than 0.8, a specialised interpreter was used, much like
\Tk's ``wish''.
To conform to the new extension methods of tcl7.0, this was changed.
Part of the result of this is that the \Xt\ world has to be explicitly
brought into existence.
This also allows the class and fallback resources to be set,
and leaves hooks for things like setting the application icon
to be added later to this binding.
The world manipulation function added is~:
\begin{description}
    \index{class@\cmd{-class}}
    \index{fallback@\cmd{-fallback\_resources}}
    \indexeditem{xtappinitialize}{\cmd{xtAppInitialize}}
        it may take parameters of \cmd{-class} and \cmd{-fallback\_resources}.
        If the class option is omitted, the binding will deduce a class
        by capitalising the first letter of the application name,
        and -- if it was an `x' -- also capitalising the second letter.
\end{description}
\bigskip
Subsequently, a bunch a root widget methods have been added to deals with
\Motif\ features related only to the main application window.
These are~:
\begin{description}
\indexeditem{mainloop}{\cmd{. mainLoop}}
    this will start the application main loop, waitting for and
    managing events.
\indexeditem{getappresources}{\cmd{. getAppResources} \sym{rsrc\_list}}
    Get the application resources. \sym{rsrc\_list} is a \Tcl list
    of quadruples \cmd{\{ \sym{name} \sym{class} \sym{default} \sym{var} \}},
    where \sym{name} is the name of the resources, \sym{class} their class.
    For each defined resource, it search a value in the application default,
    or in the resource database, and set the \Tcl variable \sym{var}
    accordingly. If not found, it sets \sym{var} to \sym{default}.
\indexeditem{processevent}{\cmd{. processEvent}}
    Process a single event (blocking if none are present).
    This is usefull only if you want to design your own main event loop.
\index{stdin@\cmd{stdin}}
\index{addinput}{\cmd{. addInput} \sym{fileId} \sym{perm} \sym{tclProc}}
    This will add an input handler to moat.
    \sym{fileId} may be one of \cmd{stdin}, \cmd{stdout}, \cmd{stderr},
    or a valid opened file, as returned by \cmd{open}.
    \sym{perm} is a sinle character permision, which might be
    \cmd{r}, \cmd{w}, or \cmd{x} respectively for read, write or exception.
    \sym{tclProc} is the tcl code that will be executed when i/o is
    ready.
    For instance, the  followin example add an interpreter that read and
    execute \moat com\-mands when they are typped in while the interface is
    running~:
    \begin{tclmode}
    # Define the interpret function, that handle error.
    proc interpret {line} {
        set code [catch {uplevel $line} result]
        if {$code == 1} then {
            puts stderr "$result in :\n\t$line"
        } else {
            if { $result != "" } {puts stderr $result}
        puts stderr "% " nonewline
    # Bind it as an input handler.
    . addInput stdin r {
        interpret [gets stdin]
    # And display the first prompt
    puts stderr "% " nonewline
    \end{tclmode}
\index{removeinput}{\cmd{. removeInput} \sym{inputId}}
    Remove the input handler specified by the given identifier.
    Identifier are uniq string returned by the corresponding
    \cmd{addInput} call.
\index{timer@Timer}
\index{addtimer}{\cmd{. addTimer} \sym{interval} \sym{tclProc}}
    Add a timer that will trigger ther execution of the
    given \Tcl\ after the specified interval.
\index{removetimer}{\cmd{. removeTimer} \sym{timerId}}
    Remove the timer specified by the given identifier. Timer
    identifier are uniq string returned by the corresponding
    call to \cmd{addTimer}.
\end{description}
%--------------------------------------------------------------------
\section{Resources}
\titles{Resources}
\label{sec:resources}
\index{resources}
Resources are inherited through the class hierarchy, they have default
values, and several different types.
In \Motif, several base classes exist, from which actual widgets are
derived. Those classes define a common set of resources, methods
and behaviors.
%--------------------------
\subsection{Resource inheritance}
Each widget belongs to a class, whose name is the widget creation
command name.
Each widget inherits resources from its super-class. For example, \cmd{xmLabel} is a
subclass of \cmd{Primitive} which in turn is a subclass of \cmd{Core}.
From \cmd{Core} it
inherits resources such as \cmd{-background}, \cmd{-height} and \cmd{-width}.
From \cmd{Primitive} it
inherits resources such as \cmd{-foreground}.
It is necessary to look at these super-classes to have the full
resource list of a \cmd{xmLabel} instance.
In addition, each class adds extra resources.
For example, \cmd{xmLabel} has the additional resources \cmd{-labelType},
\cmd{-labelPixmap} and \cmd{-labelString}, among others.
Some special resource values are inherited through multiple level of the
widget hierarchy at creation time. For instance, the \cmd{-buttonFontList}
of a bulletin board might be inherited from the \cmd{-defaultFontList}
of an ancestor sub-classing the abstracts classes \cmd{vendorShell}
or \cmd{menuShell}.
In this case, the resource value is copied and won't be modified if the original
resource is modified.
For instance, in the following example, the button inherits
its \cmd{-fontList} default value from bulletin board \cmd{-buttonFontList},
on the other hand, the button's background color is taken from the
class defaults, not from the BulletinBoard.
Pushing the button will change the BulletinBoard's \cmd{-buttonFontList}
resource, which will not update the button's font list.
\ttinclude{examples/test_hierarchy.tcl}
%--------------------------
\subsection{X Defaults}
The usual X Defaults mechanism is used to provide defaults to resources.
Default values are looked in files desiganted by the {\tt XAPPDEFAULTS}
environemnent variable, with eventually a locallization directory
(desiganted by the {\tt LANG} variable).
{\tt XAPPDEFAULTS} defaults to {\tt /usr/lib/\linebreak[0]X11/\linebreak[0]app-defaults},
and {\tt LANG} is usually not defined. In this simplest case, the
looked file is {\tt /usr/lib/X11/app-defaults/\em Application\-Name}, where
{\tt\em ApplicationName} is the class name of your application
    \index{xtappinitialize@\cmd{xtAppInitialize}}
(see {\tt xtAppInitialize}).
\smallskip
This might be overiden by \cmd{xrdb}(1).
Usually, login scripts read a user-customized resource file, often named
\cmd{.XDefaults}, or \cmd{.Xresources} using \cmd{xrdb -merge}.
It is the usual way a user configure its environement.
\smallskip
Last, some application use special configuration files, that might also
contains some resources ({\tt mwm}(1) is a good exemple of this quite
complex area,
has is looks in not less than eight different resource files...)
\medskip
Those resources files contain line specifying default resource value for
widget or widget class resources.
The syntax is~:
    \begin{center}
        \vspace{1mm}
        \sym{resourcePath} \cmd{ : } \sym{value}
        \vspace{1mm}
    \end{center}
\noindent
where \sym{value} is the string representation for the resource,
and \sym{resourcePath}
a dot-separated path naming a particular resource.
Resource paths start with an optional application name.
Without it, the default apply to all application.
The following names in the path may refer to widget class (when starting
with an upper case), to widget names (as defined by \moat\ creation command),
or to application specific scoping.
The \cmd{*} character may be used to match any portion of the resource
path.
This following examples should clarify this~: \\
\begin{tabular}{ll}
    \cmd{*Background}                    & for all widgets, in all sessions. \\
    \cmd{*PushButton.Background}        & for all the push button instances. \\
    \cmd{xterm*Background}                & for all widgets of the {\tt xterm} application.\\
    \cmd{jot.fileMenu.quit.Background}    & for the Quit button in the fileMenu of jot. \\
\end{tabular}
%--------------------------
\subsection{Resource types}
\label{res:types}
    Some resource are just string values (as \cmd{-labelString}),
    but other one have more complicated types (as colors).
    As \moat\ is a string language, all values should be manipulated in string
    representations, and \moat\ uses either \Motif\ internal either
    specific converters to make the necessary conversions.
    This section will briefly describes the main types used
    by \Tm\ and \moat.
\subsubsection*{Basic types~: Integer, Boolean and String}
\index{integer@\sym{Integer}}
\index{boolean@\sym{Boolean}}
\index{string@\sym{String}}
In \Tcl, evry variable's value is a character string. Nevertheless, some
string have a meaning as an integer, or as a boolean.
In \Tm, a \sym{String} could be any \Tcl\ string or list, correctrly
surounded by braces or double-quotes.
An \sym{Integer} is a particular string, with only decima digits in it.
A \sym{Boolean} is either one of the following words
\cmd{true}, \cmd{yes}, \cmd{on}, \cmd{false}, \cmd{no}, \cmd{off}
(in upper/lower/mixed cases), either an integer (0 means \cmd{False}).
\subsubsection*{Dimension}
\index{dimension@\sym{Dimension}}
\sym{Dimension} are particular \sym{Integer} measuring distance in screen
space.
Their actual value depends on an \cmd{-units} resource, which might
define something different horizontaly and verticaly (when based on current font
metrics for instance).
For instance, the following size set a window size to 80x24 characteres~:
\begin{tclmode}
    $window setValues \
        -units 100th_font_units \
        -width 8000 -height 2400
\end{tclmode}
\subsubsection*{Color resources}
\index{pixel@\sym{Pixel}|see \sym{Color}}
\index{color@\sym{Color}}
In \XWinsys, colors may be specified using portable
symbolic names (such as {\tt NavyBlue}) defined in the
\cmd{/usr/lib/X11/rgb.txt} file,
or RGB hexadecimal triplets of the form \cmd{\#RGB},
(with \cmd{R}, \cmd{G} and \cmd{B} being one to four hexa
 digits),
such as \cmd{\#081080}
(a dark blue, defined with 8 bits by channel).
Depending of your visual type, \XWinsys\ may alway provide you the
exact color you specified, or give you an hopefully close
approximation.
RGB values are not portable, because they depend on the screen
hardware gamma, the software contrast correction,
and the graphic board linearity.
The \cmd{rgb.txt} file should be tuned for each hardware/software
configuration (by your vendor), which is rarely well done.
%------------------------------
\subsubsection*{Font resources}
\index{font@\sym{Font}}
Font names used by X11R4 are fully qualifying dash-separated
strings, or aliased nick-names.
The general form of the full name is~:
    \begin{center}
        {\tt -\sym{maker}-\sym{name}-\sym{weight}-\sym{slant}-\sym{width}%
        -\sym{serif}-11-80-100-100-m-60-\sym{encoding}}
    \end{center}
\noindent
With~:
\begin{description}
\item[\sym{maker}:]
    The font maker, such as \cmd{adobe}, \cmd{bitstream},
    or \cmd{sgi}.
\item[\sym{name}:]
    The name for this font, as defined by the maker.
    Adobe's fonts includes \cmd{Helve\-tica}, \cmd{Zapf Chancery}, ...
\item[\sym{weight}:]
    One of \cmd{bold}, \cmd{medium}, \cmd{normal},
    \cmd{demi}, or \cmd{light}.
\item[\sym{slant}:]
    one of \cmd{o}(blic), \cmd{r}(oman).
\item[\sym{width}:]
    width of the characters, one of \cmd{normal}, \cmd{narrow}, ...
\item[\sym{serif}:]
    nothing, or \cmd{sans}.
\item[sizes]
    font size, in various units.
\item[\sym{encoding}:]
    Usually \cmd{iso8859-1}.
\end{description}
The \cmd{*} character might be used to match any of the font specifier.
On unix machines, the files
\cmd{/usr/lib/X11/fonts/*/fonts.dir} lists all existing
fonts of the actual X server.
%---------------------------
\subsubsection*{Font list}
\index{font list@Font List}
Font lists are coma separated list of fonts.
The first font in the list is the default one, the other ones are used
in coupound string.
This is quite useless by now, because there is no consensus on how
to get multi-font {\tt XmString}s, and none of the various proposition
is currently implemented in \Tm.
\medskip
Widget default font list usually derives from one of their ancestor.
Default for top-level shell are set from the \cmd{VendorShell} abstract
class, of from the {\sl X defaults} mechanism.
%---------------------------
\subsubsection*{Pixmap resources}
\index{pixmap@\sym{Pixmap}}
\index{bitmap@\sym{Bitmap}|see pixmap@\sym{Pixmap}}
Pixmaps are small rectangular arrays of pixels, used to be drown
as button, or to be tiled to fill areas.
\medskip
On color display, pixmaps may be either bi-color, using the
\cmd{-background} and \cmd{-fore\linebreak[0]ground} resources,
either full color.
Pixmaps may also be partially transparent, when they are
accompanied by a transparency mask.
\medskip
Simple bi-color pixmaps are created from a bitmap, using the current
foreground and background colors at the time they are first loaded.
Once created, the colored pixmap will be retained in the server's
memory by a caching mechanism.
At least on some X servers, this coloring will then be retained until
the \XWin\ is restarted.
The \cmd{bitmap} unix command may be used to create or modify bitmaps.
See figure~\ref{fig:pixmaps} for an example of pixmap
used to fill a button label.
\figureexample{pixmaps}{Example of Pixmap button.}
\subsubsection*{Enumerated resources}
For some resources, the value is given by a symbolic name,
which may be chosen only from a small set of legal values.
\Tm\ uses the \Motif\ standard name, without the leading
\cmd{XmN} prefix, in a free upper/lower case combination for
\cmd{setValues}.
\Tm\ will always return lower case string on \cmd{getValues}.
%----------------------------------------------------------------------------
\section{Callbacks}
\titles{Callbacks}
\label{sec:callbacks}
\index{callbacks@Callbacks}
When the user does things to a widget, it may cause the widget to take certain
actions.  For example, when a button is pressed it changes appearance to
look pressed in. Some of these actions can have \Tcl\ code attached to them,
so that the \Tcl\ code is evaluated when the action is performed. The
\Tcl\ code is said to be attached to a ``callback'' by a widget command.
For example, a push button has an \cmd{activateCallback} that is called when
the user presses and releases the left mouse button inside the widget;
it has an \cmd{armCallback} that is called when the user presses the mouse
button; it has a \cmd{disarmCallback} that is called when the user releases
the mouse button inside the widget.
\Tcl\ code is attached to a callback by giving it as the second argument to
the appropriate widget method. For example,
\begin{tclmode}
    $btn      armCallback {puts "Stop squashing me!!"}
    $btn   disarmCallback {puts "Ah... that's better"}
    $btn activateCallback {puts "Sorry Dave"; exit 0}
\end{tclmode}
The names of the callbacks available for a particular widget are derived
from the resource documentation for \Motif.  Each callback ends
with the string ``\cmd{Callback}" in its name.  Drop the \cmd{XmN} from the Motif
description to gain the widget command.  Callbacks are treated differently
to other resources because the \Xt\ treats them differently -- the
resource is not meant to be handled directly by any ordinary application.
For each \Tm\ class, a short table will list the callbacks names, and
the action that fire them.
%------------------------
\subsection{Callback substitution}
\index{callback substitution@Callback!substitution}
When \Motif\ execute a callback, in reaction to some event,
it provides it some parameters (such as the current widget)
or additional data revelant to a given class.
\Tm\ follows \Tk\ in providing the powerful mechanism of
callback substitution.
Before execution, the \Tcl command list is scanned
to look for \cmd{\%} character. Each time on is found, the word
that follows is extracted, analyzed, and if recognized, it is
substituted with the corresponding data.
For example, \cmd{\%item} in a \cmd{xmList} callback will be replaced by the item
selected, and \cmd{\%item\_position} will be replaced by its position
in the list.
An example of use of callback substitution in a list is~:
\begin{tclmode}
    .list singleSelectionCallback {
        print_info %item %item_position
    proc print_info {item position} {
        puts stdout "item was $item, at position $position"
\end{tclmode}
The table below gives the recognized tags. Their meaning will
be detailed in the context of the corresponding callbacks.
\begin{center}\begin{tabular}{llll}
  \cmd{\%click\_count}    & \cmd{\%endPos}          & \cmd{\%newinsert}     &  \cmd{\%selection\_type}\\
  \cmd{\%closure}        & \cmd{\%item\_length}    & \cmd{\%pattern\_length}& \cmd{\%set}           \\
  \cmd{\%currInsert}    & \cmd{\%item\_position}& \cmd{\%pattern\_length}& \cmd{\%startPos}      \\
  \cmd{\%currInsert}      & \cmd{\%item}            & \cmd{\%pattern}       &  \cmd{\%type}          \\
  \cmd{\%dir\_length}     & \cmd{\%length}          & \cmd{\%pattern}       &  \cmd{\%value\_length} \\
  \cmd{\%dir}             & \cmd{\%mask\_length}    & \cmd{\%ptr}           &  \cmd{\%value}         \\
  \cmd{\%doit}            & \cmd{\%mask}            & \cmd{\%reason}        &  \cmd{\%w}             \\
  \cmd{\%dragContext}     & \cmd{\%newInsert}       & \cmd{\%selected\_items}&                         \\
\end{tabular}\end{center}
\idx{\%reason} should be implemented in the version 0.9, which is substitued by the
reason why the callback was called.
The possible values, as defined in {\tt Xm/Xm.h}, with the leading {\tt XmCR\_} stripped,
are listed in the following table~:
\begin{center}\begin{tabular}{lll}
    \idx{activate}                & \idx{apply}                    & \idx{arm}                    \\
    \idx{browse\_select}        & \idx{cancel}                    & \idx{cascading}            \\
    \idx{clipboard\_data\_delete} & \idx{clipboard\_data\_request} & \idx{command\_changed}        \\
    \idx{command\_entered}        & \idx{create}                    & \idx{decrement}            \\
    \idx{default\_action}        & \idx{disarm}                    & \idx{drag}                \\
    \idx{execute}                & \idx{expose}                    & \idx{extended\_select}        \\
    \idx{focus}                    & \idx{gain\_primary}            & \idx{help}                \\
    \idx{increment}                & \idx{input}                    & \idx{lose\_primary}        \\
    \idx{losing\_focus}            & \idx{map}                        & \idx{modifying\_text\_value}\\
    \idx{moving\_insert\_cursor}& \idx{multiple\_select}        & \idx{no\_match}            \\
    \idx{none}                    & \idx{obscured\_traversal}        & \idx{ok}    \\
    \idx{page\_decrement}        & \idx{page\_increment}            & \idx{protocols}    \\
    \idx{resize}                & \idx{single\_select}            & \idx{tear\_off\_activate} \\
    \idx{tear\_off\_deactivate}    & \idx{to\_bottom}                & \idx{to\_top}                \\
    \idx{unmap}                    & \idx{value\_changed}            &        \\
\end{tabular}\end{center}
%------------------------
\subsection{Callback cross references}
\index{callback cross ref@Callback!cross reference}
The following table list all callbacks supported by \Tm\
(the full method name to add the callback code is obtained by appending
\cmd{Callback}~; they are listed in {\tt <Xm/Xm.h>}, with a {\tt XmN} prefix),
and the class in which they are first defined~:
\begin{center}\small\begin{tabular}{ll|ll}
               Name    &  Defined by    &           Name    & Defined by \\
\hline %----------------------------------------------------------
\cmd{activate}            &  Text/Button    &    \cmd{losePrimary}        &    Text            \\
\cmd{apply}                &  SelectionBox    &    \cmd{losingFocus}        &    Text            \\
\cmd{arm}                &      Button    &    \cmd{map}                &   BulletinBoard    \\
\cmd{browseSelection}    &       List        &    \cmd{modifyVerify}        &    Text            \\
\cmd{cancel}            & SelectionBox    &    \cmd{motionVerify}        &    Text            \\
\cmd{cascading}            & CascadeButton    &    \cmd{multipleSelection}    &    List            \\
\cmd{commandChanged}    &    Command        &    \cmd{noMatch}            &    SelectionBox    \\
\cmd{commandEntered}    &    Command        &                               &                    \\
\cmd{decrement}            &    ScrollBar    &    \cmd{ok}                &    SelectionBox    \\
\cmd{defaultAction}        &      List        &    \cmd{pageDecrement}        &    ScrollBar        \\
\cmd{destroy}            &      Core        &    \cmd{pageIncrement}        &    ScrollBar        \\
\cmd{disarm}            &      Button    &    \cmd{popdown}            &    Shell            \\
\cmd{drag}                &      Scale        &    \cmd{popup}                &    Shell            \\
\cmd{entry}                &    RowColumn    &    \cmd{resize}            &    Draw.            \\
\cmd{expose}            &      Draw.    &    \cmd{simple}            &    ?                \\
\cmd{extendedSelection}    &       List        &    \cmd{singleSelection}    &    List            \\
\cmd{focus}                & BulletinBoard    &    \cmd{toBottom}            &    ScrollBar        \\
\cmd{gainPrimary}        &       Text        &    \cmd{toPosition}        &    (Text)            \\
\cmd{help}                &   Mgr./Prim.  & \cmd{toTop}                &    ScrollBar        \\
\cmd{increment}            &    Scrollbar    &    \cmd{unmap}                &   BulletinBoard    \\
\cmd{input}                &  DrawingArea    &    \cmd{valueChanged}        & Text/Scale/ScrollBar \\
\end{tabular}\end{center}
%-----------------------------------------------------------------------
\section{Actions and Translations}
\label{sec:actions}
\label{sec:translations}
\titles{Actions}
Actions and translations are \Xt\ concepts that exists in \Tm\ too.
Each possible user input have a symbolic name, and they are called
``events''.
Each reaction of the interface to some event also have a name, they are
called the actions.
\index{navigation@Navigation}
Widgets may have behaviours, which are table that say what action to fire
when event arises. They are called the translations tables.
\Motif\ applications have translation tables that enable to use the
keyboard to navigate between widgets, and to select them.
This gives keyboard equivalent to mouse actions.
\medskip
The translation tables are inherited through the class hierarchy.
The list of all supported events and actions is quite long.
Look in a \Motif\ book to find about it...
%-----------------------
\subsection{Adding Actions and Translations}
\index{actions@Actions!adding}
\index{translation@Translations!adding}
Actions may be added to a widget in a similar way to the C version.
In that you define an action in a translation table which is set in the widget.
In this binding, the \Tcl\ code is placed as the arguments to the
action in the translation table.
Registering the translation using the \idx{action} \Tm\ action
links a generic action handler which in turn will handle the \Tcl\ code.
Here is what it looks like to add translation to make an arrow
turn left or right when `l' or `r' is pressed:
\begin{tclmode}
    xmArrowButton .arrow managed
    .arrow setValues -translations \
        {<Key>r: action(arrow_direction %w arrow_right)
         <Key>l: action(arrow_direction %w arrow_left)}
    proc arrow_direction {arrow direction} {
        puts stdout "Changing direction to $direction"
        $arrow setValues -arrowDirection $direction
\end{tclmode}
As with callbacks, they are supported substitutions.
In the current versions, the only one is \idx{\%w} which is substitued
with the current widget path
(Other substitutions just return the {\tt ERROR!!} magic string).
\subsection{Trigering Actions}
The method \cmd{callActionProc} is available for every widget.
The purpose of this is to allow regresion tests to be performed.
This takes an action as further parameter, using the usual \Xt\ syntax.
For example, to simulate the return key press occurring within an arrow button,
call the \cmd{ArmAndActivate()} action:
\begin{tclmode}
    .arrow callActionProc ArmAndActivate()
\end{tclmode}
This sends (by default) a ClientMessage event to the widget. Most widgets
ignore the event for most events, so this is sufficient. Some actions
require event detail, though. For example, when a mouse button release occurs,
the widget checks to see if the release occurred {\em inside} or {\em outside} the
widget.
It does this because if the event occurs inside, then the callbacks
attached to the \cmd{Activate()} action are invoked, but otherwise they are not.
To handle this, an event of type ButtonPress, ButtonRelease, KeyPress or
KeyRelease can be prepared with some fields set. For example, a ButtonRelease
occurring within the arrow can be sent by.
\begin{tclmode}
    .arrow callActionProc Activate() \
        -type ButtonPress \
        -x 0 -y 0
\end{tclmode}
Some of the Text manipulation actions require a KeyPress event, such as
\cmd{self-\linebreak[0]insert()}, which inserts the character pressed. The character is
actually encoded as a keycode, which is a hardware dependant code, too
low-level for this binding. To prepare such an event, this toolkit uses
{\em keysyms} which are abstractions for each type of key symbol.
The alphanumerics have simple representations as themselves
(`\cmd{a}', `\cmd{A}', `\cmd{2}', etc).
Others have symbolic names (`\cmd{space}', `\cmd{Tab}', `\cmd{BackSpace}', etc).
These are derived from the \XWin\ Reference manual or in the file
\cmd{<X11/keysymdefs.h>} by removing the prefix \cmd{XK\_}.
For example, to insert the three characters `\cmd{A a}' into \cmd{.text} :
\begin{tclmode}
    .text callActionProc self-insert() \
        -type KeyPress \
        -keysym A
    .text callActionProc self-insert() \
        -type KeyPress \
        -keysym space
    .text callActionProc self-insert() \
        -type KeyPress \
        -keysym a
\end{tclmode}
The set of actions that require this level of preparation of the X event
is nowhere documented explicitly. You have to read between the lines of
the Motif documentation, or guess at behaviour (or read Motif source code).
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%-----------------------------------------------------------------------
\section{Base classes}
\label{sec:abstracts}
All \Tm\ widgets derive from a small set of classes,
namely \cmd{Core}, \cmd{Primitive}, \cmd{Manager} and \cmd{Shell}.
You cannot create any widget of those classes,
because they are abstract base classes.
They are used to define sets of resources, behaviors
and methods common to all the derived widget classes which have
binding in \Tm.
This section will describe this abstract classes.
%------------------------------
\subsection{The Core Class}
\label{class:Core}
\titles{\cmd{Core}}
The Core class is the ancestor of all \Tm\ widget classes.
Hence methods and resources defined in this section equally
apply to all \Tm\ objects.
The Core class does not implement any behavior (neither action,
translation nor callback), and do even not suppose that something
should be drawn.
%---------------------------
\subsubsection{Core Methods}
The Core class defines the basic set of methods common to
all derived classes, described below~:
\begin{description}
\indexeditem{realizewidget}{\sym{w} \cmd{realizeWidget}}
    Create windows for the widget and its children,
    usually used only on the main widget, as in
    ``\cmd{.  realizeWidget}.''
\indexeditem{destroywidget}{\sym{w} \cmd{destroyWidget}}
    Destroy the widget \sym{w}, all sub-widgets
    and the associated \Tcl\ commands.
    Note that destroying the main window (\cmd{. destroyWidget}) should
    gracefully exit the main loop, while \cmd{exit 0} should exit
    the \Tcl\ interpreter.
\indexeditem{mapwidget}{\sym{w} \cmd{mapWidget}}
    Map the given widget onto screen, to make it visible. This is
    autmatically done when the widget is managed (see below).
\indexeditem{unmapwidget}{\sym{w} \cmd{unmapWidget}}
    Unmap the widget from its parent's screen, making it invisible,
    but it stay in geometry management.
\indexeditem{managechild}{\sym{w} \cmd{manageChild}}
    Bring the widget (back) under geometry management and make it appear (again).
    This equivalent to the \cmd{managed} parameter when the widget
    is created.
    Some widget cannot be managed at creation time, for instance
    when its parent needs special setting in order to handle
    it properly.
    Another example is menus and dialogs~: you might want to create
    them at the application initialisation, but it is not a good idea
    to display them permanently.
\indexeditem{unmanagechild}{\sym{w} \cmd{unmanageChild}}
    Un-managing a widget un-map it from screen, making it invisible,
    and removes it from geometry management of the parent.
\indexeditem{setsensitive}{\sym{w} \cmd{setSensitive} \sym{Boolean}}
    An insensitive widget do not respond to user input.
    When such a widget is disabled (\sym{w} \cmd{setSensitive false}),
    it is usually drawn dimmed (using a pattern).
    The main use is to disable buttons or menu items that are not allowed
    in the current state of the application.
\indexeditem{setvalues}{\sym{w} \cmd{setValues} \sym{rsrc} \sym{value} ...}
    This command is used to change resource values for an
    already existing widget. The required parameters are a list
    of pairs of resource name and string value. The following
    change the text colors of widget \cmd{.frm.text}~:
\begin{tclmode}
    .frm.text setValues \
        -background lightGray \
        -foreground #111
\end{tclmode}
    \noindent
    Each widget class define which resource may be set, their types
    and accepted values.
    Resource will be described in general in section~\ref{sec:resources},
    and with each widget description.
\indexeditem{getvalues}{\sym{w} \cmd{getValues} \sym{rsrc} \sym{variable} ...}
    This is the dual command~: given a parameter list of pairs of
    \Tm\ resource names and \Tcl\ names, it set each variable to the current
    value of the corresponding resource.
    \Motif\ reverse conversions are used for this purpose, and \Tm\
    does not actually provide all of them.
    This means that you should be able to setup all resource types,
    but may not be able to retrieve all of them.
\begin{tclmode}
    proc flash {widget {fg black} {bg red}} {
         $widget getValues \
            -background old_bg  -foreground old_fg
         $widget setValues \
            -background $bg     -foreground $fg
         wait 0.1
         $widget setValues \
            -background $old_bg -foreground $old_fg
\end{tclmode}
\index{resources}{\sym{w} \sym{resources}}
    Returns the list of all the active resources of the given widget.
    For each resource, a quadruple
    \begin{center}
        \cmd{\{\sym{name} \sym{Class} \sym{type} \sym{value}\}}
    \end{center}
    is returned.
\index{callback}{\sym{w} \sym{any}\cmd{Callback} \sym{tclProc}}
    If the widget method name contain the substring "Callback",
    then \Tm\ ask \Motif\ to register the command list given in argument.
    When th especified event occures, it will be interpreted (in the global context).
    Section~\ref{sec:callbacks} will discusses callbacks in general.
\index{parent}{\sym{w} \cmd{parent}}
    The \cmd{parent} widget command is used to get the
    parent widget name~: if a regular widget \cmd{.a.b.c} have been created,
    then \cmd{set x [.a.b.c parent]} should set the string
    \cmd{".a.b"} to the variable \cmd{x}.
    The exact result is not always obvious, because some widgets use hiden
    parents, as in dialogs.
\index{processtraversal}{\sym{w} \cmd{processTraversal} \sym{direction}}
    Change the widget that receive the keyboard input focus.
    \sym{direction} may be one of~:
    \defx{\sym{w} \cmd{processTraversal} \sym{direction}}
    \begin{description}
        \item[\idy{current}]
        \item[\idy{home}]
        \item[\idy{up}]
        \item[\idy{down}]
        \item[\idy{left}]
        \item[\idy{right}]
        \item[\idy{next}]
        \item[\idy{next\_tab\_group}]
        \item[\idy{previous\_tab\_group}]
    \end{description}
% This will be indexed in the drap&drop section !
\item[\sym{w} \cmd{dragStart} \sym{rsrc} \sym{value} ...]
\item[\sym{w} \cmd{dropSiteRegister} \sym{rsrc} \sym{value} ...] \dopar
    See the {\sl Drad and Drop} section (page~\pageref{sec:dragdrop}) for details
    about this mehods.
% This will be indexed in the Xt drawing section.
\item[\sym{w} \cmd{getGC} \sym{rsrc} \sym{value} ...] \dopar
    This method is used to retrieve the \Xlib\ graphical context of a widget.
    There must be at leat one resource defined.
    The allowed resources are \cmd{-background} and \cmd{-foreground}.
    See section on drawn widget (page~\pageref{sec:drawn}) for information
    about user defined graphics in \Tm\ widgets.
\indexeditem{callactionproc}{\sym{w} \cmd{callActionProc}}
    Call an action procedure, usually used to test \moat, or your own code.
\end{description}
%-----------------------------
\subsubsection{Core resources}
\label{class:core}
\index{core class@\cmd{Core}}
\begin{rsrctable}{Core}
  \idx{-accelerators}        &  \sym{none}    &    \sym{String}    \\
  \idx{-background}            & \sym{dynamic}    &    \sym{Color}        \\
  \idx{-backgroundPixmap}    &  \sym{none}    &    \sym{Pixmap}    \\
  \idx{-borderColor}        & \sym{dynamic}    &     \sym{Color}        \\
  \idx{-borderWidth}        &    \cmd{1}    &     \sym{Integer}    \\
  \idx{-heigth}                & \sym{dynamic}    &     \sym{Integer}    \\
  \idx{-mappedWhenManaged}    &  \cmd{True}    &    \sym{Boolean}    \\
  \idx{-sensitive}            &  \cmd{True}    &    \sym{Boolean}    \\
  \idx{-translations}        &  \sym{none}    &    \sym{String}    \\
  \idx{-width}                & \sym{dynamic}    &    \sym{Integer}    \\
  \idx{-x}                    &    \cmd{0}    &    \sym{Integer}    \\
  \idx{-y}                    &    \cmd{0}    &    \sym{Integer}    \\
\end{rsrctable}
The table describes resource common to all widgets.
A \cmd{Core} widget (i.e. any widget) basically is some empty
rectangle, with an optional border.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%------------------------------
\subsection{The Primitive class}
\label{class:primitive}
\titles{\cmd{Primitive}}
\index{primitive@\cmd{Primitive}}
The \cmd{Primitive} class derives from the \cmd{Core} class.
This abstract class is designed to define resouces and behaviour
common to any widget that may have something
drawn on it.
As the user sees something, \cmd{Primitive} is able to define
some very general behaviour, which appear as translations, actions
and callbacks.
%---------------------------------
\subsubsection{Primitive resources}
The table below describes the resources revelant for all
widget deriving from \cmd{Primitive}.
\begin{rsrctable}{Primitive}
  \idx{-bottomShadowColor}        & \sym{dynamic}    & \sym{Color} \\
  \idx{-bottomShadowPixmap}        & \sym{none}    & \sym{Pixmap} \\
  \idx{-foreground}                & \sym{dynamic}    & \sym{Color} \\
  \idx{-highlightColor}         &  \sym{none}    & \sym{Color} \\
  \idx{-highlightOnEnter}        &  \cmd{False}    & \sym{Boolean} \\
  \idx{-highlightThickness}        &   \cmd{2}        & \sym{Integer} \\
  \idx{-navigationType}            &  \cmd{none}    & \idy{none} \\
                                  &                & \idy{tab\_group} \\
                                  &                & \idy{sticky\_tab\_group} \\
                                  &                & \idy{exclusive\_tab\_group} \\
  \idx{-shadowThickness}        &   \cmd{2}        & \sym{Integer} \\
  \idx{-topShadowColor}            & \sym{dynamic}    & \sym{Color} \\
  \idx{-topShadowPixmap}        &  \sym{none}    & \sym{Pixmap} \\
  \idx{-traversalOn}            &  \cmd{True}    & \sym{Boolean} \\
  \idx{-unitType}                &  \cmd{pixels}    & \idy{pixels} \\
                                  &                & \idy{100th\_millimeters} \\
                                  &                & \idy{1000th\_inches} \\
                                  &                & \idy{100th\_points} \\
                                  &                & \idy{100th\_font\_units} \\
\end{rsrctable}
Simple bi-color drawing are done using Primitive's foreground color,
over the Core's background. Other colors default to mixing of this
two ones, at the time the widget is created.
Primitive objects might be highlighted when they are ``entered''
(get the input focus), by drawing a border around them,
of a given color.
They can also be enclosed by a beweled shadow frame, to make
them appear standing in or out (so called ``3D shapes'').
Using the \cmd{-unitType} resource, one might choose between screen
dependend units (the default), font related units, or device indepedant
units. This will affect any subsequent dimensions resources for that widget only.
\cmd{-navigationType} refer to the way
keyboard may be used to navigate between widgets, without using
the mouse. This is used by managers to quickly navigating between input
fields, for instance using the \cmd{<Tab>} key.
\subsubsection{Primitive callbacks}
    \begin{center}\begin{tabular}{|l|l|}
    \hline %------------------------------------------------------------------
            Method name    & Why \\
    \hline %------------------------------------------------------------------
    % Manager/Primitive
           \idx{helpCallback}    & The help key is pressed. \\
    % Primitive
        \idx{destroyCallback}    & Widget is destroyed. \\
    \end{tabular}\end{center}
The table above give the only two callbacks defined for evry
drawable widgets, for which the only supported substitution
is \cmd{\%w} that expand to the widget path.
\cmd{destroyCallback} may be used to automaticaly call some cleanup
procedure when a widget is deleted.
When the \cmd{Help()} action arised (either through the \cmd{KHelp}
key, either by a virtual binding), \Motif\ looks for a callback to
execute in the current widget. If none is found, it look in the
parent, the parent's parent, and so one up to the main window.
Hence, the \cmd{helpCallback} may be used to implement a
general or a context sensitive help facility.
%-----------------------------------------
\subsubsection{Primitive actions}
As for any widgets, there is action that match each callback.
This actions trigger the callbacks execution and the standard widget responses,
if any.
For the \cmd{Primitive} class, they are~:
\begin{description}
\indexeditem{help()}{\cmd{Help()}}
    If there is no callback defined for this widget, this action will propagate
    the help action to the widget's parent. If no callback are defined upto
    the root widget, the action will simply be forgeted.
\indexeditem{destroy()}{\cmd{Destroy()}}
    The callbacks will be called before destroying a widget, to enable
    application specific cleanup to take place automatically when a widget is
    destroyed.
\end{description}
\subsubsection{Primitive translations}
The only translation defined for the \cmd{Primitive} class is~:
\begin{center}
    \cmd{<KHelp>: Help()}
\end{center}
which means that the symbolic key \cmd{KHelp} will trigger the
\cmd{Help()} action. This key is defined in a \cmd{keysym} file used by
the \XWin\ server.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Shell classes}
\label{class:Shell}
\titles{\cmd{Shell}}
The \Tm\ Shell classes are used to define resources and behaviours
that are common to evry widgets that use theyre own window, such
as top level windows, popup menues, and dialogs.
\Motif\ describe several different base class for this purpose,
some inhetited from \Xt, some defined inside \Motif~:
\begin{description}
\indexeditem{shell}{\cmd{Shell}}
    The basic shell, ancestor of all other abstract shell classes.
\indexeditem{toplevelshell}{\cmd{TopLevelShell}}
    Top level windows are responsibles of iconization.
\indexeditem{transientshell}{\cmd{TransientShell}}
    Transient windows are temporary windows, that should not stay visible on
    screen, and should be iconized along with the top level they are transient
    for.
\indexeditem{vendorshell}{\cmd{VendorShell}}
    Vendor shell resources are setup in the {\sl X\/} serveur, and contain
    meaningfull defaults for a particular implementation.
\indexeditem{wmshell}{\cmd{WMShell}}
    Handle protocols to assure communications between the application and the
    window manager.
\end{description}
The tables below display the resources avalaible for all those
shells.
\begin{rsrctable}{ApplicationShell}
    \idx{-argc}                    & Set by \cmd{XtInitialize()}
                                                & \sym{Integer}        \\
    \idx{-argv}                    & Set by \cmd{XtInitialize()}
                                                & \sym{String Array}\\
\end{rsrctable}
\begin{rsrctable}{TopLevelShell}
    \idx{-iconic}                &    \cmd{False}    &    \sym{Boolean}    \\
    \idx{-iconName}                &    \cmd{""}    &    \sym{String}    \\
    \idx{-iconNameEncoding}        &\cmd{xa\_string}&    \idy{compound\_text}    \\
                                &                &    \idy{xa\_string}    \\
\end{rsrctable}
\begin{rsrctable}{TransientShell}
      \idx{-transientFor}            &    \sym{none}    &    \sym{Widget}    \\
\end{rsrctable}
\begin{rsrctable}{VendorShell}
    \idx{-defaultFontList}        & \sym{dynamic}    & \sym{font list}    \\
    \idx{-deleteResponse}        & \cmd{destroy}    & \idy{do\_nothing}    \\
                                &                & \idy{unmap}        \\
                                &                & \idy{destroy}    \\
    \idx{-keyboardFocusPolicy}    & \cmd{explicit}& \idy{explicit}    \\
                                &                & \idy{pointer}    \\
    \idx{-mwmDecorations}        &    \cmd{-1}    & \sym{Integer}        \\
    \idx{-mwmFunctions}            &    \cmd{-1}    & \sym{Integer}    \\
    \idx{-mwmInputMode}            &    \cmd{-1}    & \sym{Integer}    \\
    \idx{-mwmMenu}                &    \cmd{""}    & \sym{String}    \\
    \idx{-shellUnitType}        &  \cmd{pixels}    & \idy{pixels} \\
                                &                & \idy{100th\_milimeters} \\
                                &                & \idy{1000th\_inches} \\
                                &                & \idy{100th\_points} \\
                                &                & \idy{100th\_font\_units} \\
    \idx{-useAsyncGeometry}        &    \cmd{False}    & \sym{Boolean}    \\
\end{rsrctable}
\begin{rsrctable}{WMShell}
    \idx{-baseHeight}            &  \sym{none}    & \sym{Integer}    \\
    \idx{-baseWidth}            &  \sym{none}    & \sym{Integer}    \\
    \idx{-heightInc}            &  \sym{none}    & \sym{Integer}    \\
    \idx{-iconMask}                &  \sym{none}    & \sym{Pixmap}    \\
    \idx{-iconPixmap}            &  \sym{none}    & \sym{Pixmap}    \\
    \idx{-iconWindow}            &  \sym{none}    & \sym{Window}    \\
    \idx{-iconX}                &    \cmd{-1}    & \sym{Integer}    \\
    \idx{-iconY}                &    \cmd{-1}    & \sym{Integer}    \\
    \idx{-initialState}            & \cmd{normalState}
                                                & \idy{iconicState} \\
                                &                & \idy{normalState} \\
    \idx{-input}                &    \cmd{False} & \sym{Boolean}    \\
    \idx{-maxAspectX}            &    \sym{none}    & \sym{Integer}    \\
    \idx{-maxAspectY}            &    \sym{none}    & \sym{Integer}    \\
    \idx{-maxHeight}            &    \sym{none}  & \sym{Integer}    \\
    \idx{-maxWidth}                &    \sym{none}  & \sym{Integer}    \\
    \idx{-minAspectX}            &    \sym{none}    & \sym{Integer}    \\
    \idx{-minAspectY}            &    \sym{none}    & \sym{Integer}    \\
    \idx{-minHeight}            &    \sym{none}  & \sym{Integer}    \\
    \idx{-minWidth}                &    \sym{none}  & \sym{Integer}    \\
    \idx{-title}                & \cmd{argv[0]}    & \sym{String}    \\
    \idx{-titleEncoding}        &\cmd{xa\_string}&    \idy{compound\_text}    \\
                                &                &    \idy{xa\_string}    \\
    \idx{-transient}            &    \cmd{False} & \sym{Boolean}   \\
    \idx{-waitForWm}            &    \cmd{True}    & \sym{Boolean}   \\
    \idx{-widthInc}                &    \sym{none}  & \sym{Integer}   \\
    \idx{-windowGroup}            &                & \sym{Window}    \\
    \idx{-winGravity}            & \sym{dynamic} & \sym{Integer}   \\
    \idx{-wmTimeout}            & \cmd{5000}ms    & \sym{Integer}      \\
\end{rsrctable}
\begin{rsrctable}{Shell}
    \idx{-allowShellResize}        &   \cmd{False} & \sym{Boolean}   \\
    \idx{-geometry}                &    \cmd{""}    & \sym{String}    \\
    \idx{-overrideRedirect}        &   \cmd{False} & \sym{Boolean}   \\
    \idx{-saveUnder}            &   \cmd{False} & \sym{Boolean}   \\
    \idx{-visual}                &   Inherited    & \sym{String}    \\
\end{rsrctable}
\paragraph{Window resizing constraints}
\index{resizing@Resizing}
\index{window resizing@Window resizing}
\index{constraints@Constraints}
may be set on its dimensions of the window, or on
its aspect (ratio between width and height).
Beside minimal and maximal dimensions, window dimension may be
constrained to follow a given increment. For instance, using the following
setting, the only width allowed for interactive resizing will be 150 and
250~:
\begin{tclmode}
    -minWidth 100 -baseWidth 50 -widthInc 100 -maxWidth 300
\end{tclmode}
\index{aspect@Aspect}
Window aspects are set using a numerator/denominator formula~:
\begin{equation}
\frac{\cmd{minAspectX}}{\cmd{minAspectY}}
    \leq    \frac{\mbox{width}}{\mbox{height}}
    \leq    \frac{\cmd{minAspectX}}{\cmd{minAspectY}}
    \nonumber
\end{equation}
Hence, the following setting constrains the width to stay between a third and
twice the height~:
\begin{tclmode}
    -minAspectX 1 -manAspectY 3 -maxAspectX 2 -minAspectY 1
\end{tclmode}
\medskip
Interactive window resizing may also be ignored by setting the
\cmd{-allowShellResize} resource to \cmd{False}.
\paragraph{Window icon resouces}
\index{icon@Icon}
may be used to define the window icon type, its placement, ...
Icons may be drawn using a (possibly partially transparent) pixmap, or
by using a specific alternate window (\cmd{-iconWindow}). A window may be
setup to appear in iconic state at creation (\cmd{-initialState iconicState}),
and its current state may be retrieved or changed using the \cmd{-iconic}
resource.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------------------------------------------------
\section{Basic widgets}
\label{sec:basic}
This section will detail the basic \Motif\ widgets, from which all the
more sofisticated one derives.
%------------------------
\subsection{\cmd{xmLabel}}
\index{xmlabel@\cmd{xmLabel}}
\index{label@Label|see\cmd{xmLabel}}
\titles{\cmd{xmLabel}}
A label widget is just a small written piece of text.
For instance, executing the following \moat\ script
    \ttinclude{examples/hello.tcl}
\noindent
would display the following window on your screen~:
    \window{hello}
Note that the text will be broken into seperate lines only if
you put newlines in it.
It may contains non-ascii characteres (using the encoding defined in the
font, usually \cmd{ISO8859-1}).
See figure~\ref{fig:bigLabel} for a more complexe example.
    \figureexample{bigLabel}{A more complex label example.}
%-------------------------
\subsubsection*{Resources}
\begin{rsrctable}{xmLabel}
    \idx{-accelerator}                &    \cmd{""}    &    \sym{String} \\
    \idx{-acceleratorText}            &    \cmd{""}    &    \sym{String} \\
    \idx{-alignment}                & center        &    \idy{alignment\_center} \\
                                    &                &    \idy{alignment\_beginning} \\
                                    &                &    \idy{alignment\_end} \\
    \idx{-fontList}                    & inherited        &    \sym{fontList} \\
    \idx{-labelInsensitivePixmap}    & \sym{none}    &    \sym{Pixmap} \\
    \idx{-labelPixmap}                & \sym{none}    &    \sym{Pixmap} \\
    \idx{-labelString}                &  widget name    &    \sym{String} \\
    \idx{-labelType}                & \cmd{string}  &    \idy{string} \\
                                      &               &    \idy{pixmap} \\
    \idx{-marginBottom}                &    \cmd{0}     &    \sym{Integer} \\
    \idx{-marginHeight}                &    \cmd{0}     &    \sym{Integer} \\
    \idx{-marginLeft}                &   \cmd{0}     &    \sym{Integer} \\
    \idx{-marginRight}                &   \cmd{0}     &    \sym{Integer} \\
    \idx{-marginTop}                &     \cmd{0}        &    \sym{Integer} \\
    \idx{-marginWidth}                &     \cmd{0}        &    \sym{Integer} \\
    \idx{-mnemonic}                    &    \cmd{""}    &    \sym{String} \\
    \idx{-mnemonicCharSet}            &    dynamic        &    \sym{String} \\
    \idx{-recomputeSize}            &  \cmd{True}    &    \sym{Boolean} \\
    \idx{-stringDirection}            & l\_to\_r        &    \idy{string\_direction\_l\_to\_r} \\
                                    &                &    \idy{string\_direction\_r\_to\_l} \\
\end{rsrctable}
The label may display the \cmd{-labelString} or
\cmd{-labelPixmap} resource, depending of the \cmd{-labelType} value.
Labels are always top/bottom centered (inside their margins), but
may be left or right flushed or centered, depending on \cmd{-alignment}.
When a label is insensitive, the displayed text is grayed using a 50\%
pattern. Pixmap type labels may also be defined to display a different
pixmap using \cmd{-label\-Insensitive\-Pixmap}.
When the displayed material changes, the label may or may not recompute
its size, depending of \cmd{-recomputeSize}.
Some resources are only used in derived class.
\medskip
The following resources are inherited from the
Primitive (page~\pageref{rsrc:Primitive}),
and Core classes (page~\pageref{rsrc:Core})~:
\begin{center}\begin{tabular}{lc|lc}
    \cmd{-accelerators}            & (Core)    &
    \cmd{-backgroundPixmap}        & (Core)    \\
    \cmd{-background}            & (Core)    &
    \cmd{-borderColor}            & (Core)    \\
    \cmd{-borderWidth}            & (Core)    &
    \cmd{-bottomShadowColor}    & (Primitive)    \\
    \cmd{-bottomShadowPixmap}    & (Primitive)    &
    \cmd{-foreground}            & (Primitive)    \\
    \cmd{-heigth}                & (Core)    &
    \cmd{-highlightColor}        & (Primitive)    \\
    \cmd{-highlightOnEnter}        & (Primitive)    &
    \cmd{-highlightPixmap}        & (Primitive)    \\
    \cmd{-highlightThickness}    & (Primitive)    &
    \cmd{-mappedWhenManaged}    & (Core)    \\
    \cmd{-navigationType}        & (Primitive)    &
    \cmd{-sensitive}            & (Core)    \\
    \cmd{-shadowThickness}        & (Primitive)    &
    \cmd{-topShadowColor}        & (Primitive)    \\
    \cmd{-topShadowPixmap}        & (Primitive)    &
    \cmd{-translations}            & (Core)    \\
    \cmd{-traversalOn}            & (Primitive)    &
    \cmd{-unitType}                & (Primitive)    \\
    \cmd{-width}                & (Core)    &
    \cmd{-x}                    & (Core)    \\
    \cmd{-y}                    & (Core)    &
                                &        \\
\end{tabular}\end{center}
%-------------------------
\subsubsection*{Callbacks}
Label do not define specific callbacks, but just inherit them from
the Primitive class, namely \cmd{helpCallback}
and \cmd{destroyCallback}.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\cmd{xmText}, \cmd{xmScrolledText} and \cmd{xmTextField}}
\titles{\cmd{xmText}, \cmd{xmTextField}}
\index{xmtext@\cmd{xmText}}
\index{xmscrolledtext@\cmd{xmScrolledText} |see \cmd{xmText}}
\index{xmtextfield@\cmd{xmTextField}}
\index{text@Text|see \cmd{xmText}}
Text widgets display a text string, but also allow the user to edit it.
A \cmd{xmTextField} widget display a single-line editable text,
while a \cmd{xmText} widget usually span multiple lines.
A \cmd{xmScrolledText} would automatically
displays scroll bars if it is larger than the alloted space on screen.
Those \cmd{xmScrollBar}s enable the user to change the currently viewed
part of the text.
Selection of parts of text are done by keyboard or mouse
interactions, as described below in the translations.
\medskip
A scrolled text widget \sym{w} is a composite widget that have the
following childrens~:
\begin{center}\begin{tabular}{lll}
    \sym{w}\cmd{.HorScrollBar} & \sym{w}\cmd{.VertScrollBar} & \sym{w}\cmd{.ClipWindow}    \\
\end{tabular}\end{center}
The associated \Tcl proc might be used to directly access them, as in the
following example~:
\begin{tclmode}
    xmScrolledText .txt managed
    set rsrc_list [.txt.ClipWindow resources]
\end{tclmode}
\subsubsection*{Methods}
In addition to the standard \cmd{Core} methods, texts widgets defined
the following new ones to deal with selection and clipboard~:
\begin{description}
    \indexeditem{setstring}{\sym{txt} \cmd{setString} \sym{the\_text}}
        Change the current text to \sym{the\_text}.
    \indexeditem{getstring}{\sym{txt} \cmd{getString}}
        return the whole text as result.
    \indexeditem{getsubstring}{\sym{txt} \cmd{getSubString} \sym{start} \sym{len} \sym{var}}
        Set the \Tcl variable \sym{var} to the substring starting at position
        \sym{start} for \sym{len} characteres. If \sym{len} if larger than
        some internal threshold, only the first part of the text will be set to \sym{var}.
        \defx{\sym{txt} \cmd{getSubString} \sym{start} \sym{len} \sym{var}}
        This method returns either \idy{succeded}, \idy{truncated} or \idy{failed}.
    \indexeditem{insert}{\sym{txt} \cmd{insert} \sym{position} \sym{string}}
        Insert \sym{string} in the text, starting at position \sym{position}.
        Use zero to insert at the beginning of the text.
    \indexeditem{replace}{\sym{txt} \cmd{replace} \sym{start} \sym{stop} \sym{string}}
        Replace the portion of text between \sym{start} and \sym{stop} by
        the new value \sym{string}.
    \indexeditem{setselection}{\sym{txt} \cmd{setSelection} \sym{start} \sym{stop}}
        Set the current selection to the substring starting at \sym{start},
        end ending at \sym{stop}.
    \indexeditem{getselection}{\sym{txt} \cmd{getSelection}}
        Returns the primary selection of the text. If nothing
        is selected, just returns nothing.
    \indexeditem{getselectionposition}{\sym{txt} \cmd{getSelectionPosition} \sym{start} \sym{stop}}
        If there is something selected, set the \Tcl variables
        \sym{start} and \sym{stop} accordingly and returns
        \cmd{true}, else returns \cmd{false}.
    \indexeditem{clearselection}{\sym{txt} \cmd{clearSelection}}
        deselect the current selection.
    \indexeditem{remove}{\sym{txt} \cmd{remove}}
        remove the currently selected part of the text.
    \indexeditem{copy}{\sym{txt} \cmd{copy}}
        copy the current selection into the clipboard.
    \indexeditem{cut}{\sym{txt} \cmd{cut}}
        copy the current selection into the clipboard, then remove
        it from the text.
    \indexeditem{paste}{\sym{txt} \cmd{paste}}
        replace the current selection by the clipboard contains.
    \indexeditem{setaddmode}{\sym{txt} \cmd{setAddMode} \sym{bool}}
        Set weither or not the text is in ``add mode''.
        When in add mode, text insertion won't modify the
        current selection.
    \indexeditem{sethighlight}{\sym{txt} \cmd{setHighlight} \sym{start} \sym{stop} \sym{mode}}
        Change the highlight appearance of the text between
        \sym{start} and \sym{stop}, but not the current
        selection.
        \defx{\sym{txt} \cmd{setHighlight} \sym{start} \sym{stop} \sym{mode}}
        \sym{mode} may be either \idy{normal}, \idy{selected}
        or \idy{secondary\_selected}.
    \indexeditem{findstring}{\sym{txt} \cmd{findString} \sym{start} \sym{stop} \sym{string} \sym{dir} \sym{pos}}
        Search the current text for \sym{string} between the position
        \sym{start} and \sym{stop}.
        \defx{\sym{txt} \cmd{findString} \sym{start} \sym{stop} \sym{string}}
        The direction \sym{dir} might be either \idy{forward}, either \idy{backward}.
        If found, the position of the first occurence is set to the \Tcl variable
        \sym{pos}, and it returns \cmd{true}, else it returns \cmd{false}.
    \indexeditem{getinsertposition}{\sym{txt} \cmd{getInsertPosition}}
        Returns the position of the insert cursor. Zero is the
        first charactere in the text.
    \indexeditem{setinsertposition}{\sym{txt} \cmd{setInsertPosition} \sym{position}}
        Set the cursor insertion point.
    \indexeditem{getlastposition}{\sym{txt} \cmd{getLastPosition}}
        Returns the position of the last caractere in the text
        buffer, in other words, its length.
    \indexeditem{scroll}{\sym{txt} \cmd{scroll} \sym{lines}}
        Scroll the text widget by \sym{lines} lines. A positive value
        scroll it upward, a negative value backward.
    \indexeditem{showposition}{\sym{txt} \cmd{showPosition} \sym{position}}
        Scroll the text such that \sym{position} become visible.
    \indexeditem{gettopcharactere}{\sym{txt} \cmd{getTopCharacter}}
        Returns the position of the first visible charactere of
        the text in the widget.
    \indexeditem{settopcharactere}{\sym{txt} \cmd{setTopCharacter} \sym{position}}
        Scroll the text so that \sym{position} will be the first
        visible charactere in the widget.
    \indexeditem{disableredisplay}{\sym{txt} \cmd{disableRedisplay}}
        The text will not being redisplayed.
    \indexeditem{enableredisplay}{\sym{txt} \cmd{enableRedisplay}}
        The text will redisplay automatically when it changes.
    \indexeditem{geteditable}{\sym{txt} \cmd{getEditable}}
        Returns \cmd{true} if the text is editable (that is,
        the user can edit it), \cmd{false} if not.
    \indexeditem{seteditable}{\sym{txt} \cmd{setEditable} \sym{bool}}
        Set the edit permition flag of the text widget.
     \indexeditem{setsource}{\sym{txt} \cmd{setSource} \sym{ref} \sym{top} \sym{ins}}
        Set the text edited/displayed by this widget to the one
        that is also edited/displayed by the text widget
        \sym{ref}.
        The text will be scrolled such that the top charactere
        will be \sym{top}, and the insertion cursor positionned
        at \sym{ins}.
\end{description}
\subsubsection*{Resources}
\begin{rsrctable}{xmText}
    \idx{-autoShowCursorPosition}    &    \cmd{True}    &    \sym{Boolean} \\
    \idx{-cursorPosition}            &    \cmd{0}        &    \sym{Integer} \\
    \idx{-editable}                    &   \cmd{True}  &   \sym{Boolean} \\
    \idx{-editMode}                    & \cmd{single\_line\_edit}
                                                    & \idy{multiple\_line\_edit}, \\
                                    &                & \idy{single\_line\_edit}. \\
    \idx{-marginHeight}                &   \cmd{5}     &   \sym{Integer} \\
    \idx{-marginWidth}                &   \cmd{5}     &   \sym{Integer} \\
    \idx{-maxLength}                & \sym{maxint}  &   \sym{Integer} \\
    \idx{-source}                    &  new source    &   \sym{Text Source} \\
    \idx{-topCharacter}                &   \cmd{0}     &   \sym{Integer} \\
    \idx{-value}                    &    \cmd{""}    &    \sym{String} \\
    \idx{-verifyBell}                &   \cmd{True}  &   \sym{Boolean} \\
\end{rsrctable}
\begin{rsrctable}{xmTextInput}
    \idx{-pendingDelete}            &   \cmd{True}  &   \sym{Boolean} \\
    \idx{-selectionArray}            &    not supported &    \\
    \idx{-selectionArrayCount}        &    not supported &    \\
    \idx{-selectThreshold}            &   \cmd{5}     &   \sym{Integer} \\
\end{rsrctable}
\begin{rsrctable}{xmTextOutput}
    \idx{-blinkRate}                &  \cmd{500}ms    &    \sym{Integer} \\
    \idx{-columns}                    & computed from \cmd{-width} &       \sym{Integer} \\
    \idx{-cursorPositionVisible}    &   \cmd{True}  &   \sym{Boolean} \\
    \idx{-fontList}                    &  Inherited    &    \sym{Font list} \\
    \idx{-resizeHeight}                &  \cmd{False}    &   \sym{Boolean} \\
    \idx{-resizeWidth}                &  \cmd{False}    &   \sym{Boolean} \\
    \idx{-rows}                        & computed from \cmd{-height} &     \sym{Integer} \\
    \idx{-wordWrap}                    &  \cmd{False}    &   \sym{Boolean} \\
\end{rsrctable}
The \cmd{xmText} widget inherits resources from two abstract classes,
\idx{xmTextInput} and \idx{xm\-Text\-Output}.
\cmd{xmTextField} use the resource subset that correspond to single-line
text (e.g. it does not have a \cmd{-editMode} resource).
The text source resource might be used to open multiple windows editing a
single text, as in the exemple below~: \note{It needs a convertion to/from Pointer !}
\begin{tclmode}
    xmPanedWindow .top managed
    xmScrolledText .top.a managed \
        -editMode multi_line_edit \
        -value {Que j'aime a faire apprendre un nombre utile aux sages,
                Immortel Archimede, artiste, ingenieur,
                qui de ton jugement peut priser la valeur,
                pour moi il eu de serieux avantages.}
    xmScrolledText .top.b managed \
        -editMode multi_line_edit
    .top.b setSource .top.a 0 0
\end{tclmode}
The \cmd{xmTextInput} and \cmd{xmTextOutput} abstract classes are just used
to group resources dedicated to text editing or displaying.
Large text should be displayed or edited with the \cmd{xmScrolledText}
widget, which automatically
provides scroll bars when needed.
\medskip
Furthermore, text widgets inherit any resources defined in the
Core (page~\pageref{rsrc:Core}),
Primitive (page~\pageref{rsrc:Primitive}),
and \cmd{xmLabel} (page~\pageref{rsrc:xmLabel}) classes.
\begin{center}\begin{tabular}{lc|lc}
    \cmd{-accelerators}            & (Core)    &
    \cmd{-alignment}            & (Label)    \\
    \cmd{-backgroundPixmap}        & (Core)    &
    \cmd{-background}            & (Core)    \\
    \cmd{-borderColor}            & (Core)    &
    \cmd{-borderWidth}            & (Core)    \\
    \cmd{-bottomShadowColor}    & (Primitive)    &
    \cmd{-bottomShadowPixmap}    & (Primitive)    \\
    \cmd{-fontList}                & (Label)    &
    \cmd{-foreground}            & (Primitive)    \\
    \cmd{-heigth}                & (Core)    &
    \cmd{-highlightColor}        & (Primitive)    \\
    \cmd{-highlightOnEnter}        & (Primitive)    &
    \cmd{-highlightPixmap}        & (Primitive)    \\
    \cmd{-highlightThickness}    & (Primitive)    &
    \cmd{-labelPixmap}            & (Label)    \\
    \cmd{-labelString}            & (Label)    &
    \cmd{-labelType}            & (Label)    \\
    \cmd{-mappedWhenManaged}    & (Core)    &
    \cmd{-marginBottom}            & (Label)    \\
    \cmd{-marginLeft}            & (Label)    &
    \cmd{-marginRight}            & (Label)    \\
    \cmd{-marginTop}            & (Label)    &
    \cmd{-navigationType}        & (Primitive)    \\
    \cmd{-recomputeSize}        & (Label)    &
    \cmd{-sensitive}            & (Core)    \\
    \cmd{-shadowThickness}        & (Primitive)    &
    \cmd{-stringDirection}        & (Label)    \\
    \cmd{-topShadowColor}        & (Primitive)    &
    \cmd{-topShadowPixmap}        & (Primitive)    \\
    \cmd{-translations}            & (Core)    &
    \cmd{-traversalOn}            & (Primitive)    \\
    \cmd{-unitType}                & (Primitive)    &
    \cmd{-width}                & (Core)    \\
    \cmd{-x}                    & (Core)    &
    \cmd{-y}                    & (Core)    \\
\end{tabular}\end{center}
%-------------------------------------
\subsubsection*{Text verify callbacks}
The text widgets allows special processing by the application of text
entered.
After a character has been typed, or text pasted in, initial
processing by the Text widget determines what the user is
entering. This text is then passed to special callback
functions. These functions can make copies of the text, can
alter it, or can set a flag to say do not display it. Simple
uses for this are a password entry widget that reads the text
but does not display it (or echoes `\cmd{*}' instead), or text
formatting widgets.
The callback mechanism for this is basically the same as for
other callbacks, and similar sorts of substitutions are
allowed. For example, the term \cmd{\%currInsert} is replaced
by the current insertion position.  Other substitutions do not
give a value, but rather give the name of a \Tcl\ variable.
This allows the application to change the value as required.
For example, to turn off echoing of characters,
the following should be done~:
\begin{tclmode}
    .text modifyVerifyCallback {
           set %doit false
\end{tclmode}
An alternate style would have been to call a separate procedure
to handle the work to be done.
The \Tcl\ variable is in the context of the callback caller, so
\cmd{upvar} should be used~:
\begin{tclmode}
    .text modifyVerifyCallback {no_echo %doit}
    proc no_echo {doit} {
           upvar 1 $doit do_insert
           set do_insert false
\end{tclmode}
Actually, the \Tcl\ variable here is the global variable
\cmd{\_Tm\_Text\_Doit}.  For this reason, variables beginning with
\cmd{\_Tm\_} are reserved for use by the \Tm\ library.
%-------------------------
\subsubsection*{Callbacks}
The supported callbacks are~:
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
    Method name                    & Why \\
\hline %------------------------------------------------------------------
           \idx{helpCallback}    & The help key is pressed. \\
        \idx{destroyCallback}    & Widget is destroyed. \\
       \idx{activateCallback}    & Some event trigger the Activate action. \\
    \idx{gainPrimaryCallback}    & Ownership of the primary selection is gained. \\
    \idx{losePrimaryCallback}    & Ownership of the primary selection is loosed. \\
    \idx{losingFocusCallback}    & Before losing input focus. \\
   \idx{modifyVerifyCallback}    & Before deletion or insertion. \\
   \idx{motionVerifyCallback}    & Before moving the insertion point. \\
   \idx{valueChangedCallback}    & Some text was deleted or inserted. \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
The following callbacks substitutions are defined for the text
specific callbacks~:
\begin{description}
    \item{\idx{\%doit}}\dopar
            In a verify callback, the variable name of the flag to
            know if we should do it.
    \item[\idx{\%currInsert}, \idx{\%newInsert}] \dopar
            In a \cmd{motionVerifyCallback}, the insertion point before
            and after the projected motion.
    \item[\idx{\%startPos}, \idx{\%endPos}] \dopar
            Define a substring in the widget's text string.
    \item[\idx{\%ptr}, \idx{\%length}] \dopar
        Define the string which is to be modifyed, in a
        \cmd{modifyVerify} callback.
        For instance, the
        following example may be used to chande inputs to uppercase~:
        \begin{tclmode}
        proc allcaps {ptr length} {
           upvar 1 $ptr p
           upvar 1 $length l
           if {$l == 0} return
           set upper [string toupper $p]
           set p $upper
        .text modifyVerifyCallback {allcaps %ptr %length}
        \end{tclmode}
\end{description}
In addition, text widgets inherit callbacks from
the Primitive class, namely help
and destroy callbacks.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------
\subsection{Buttons}
\titles{Buttons}
\index{button@Button}
\Motif\ use several flavors of the button to be pushed, namely~:
\begin{description}
    \index{push button@Push button|see \cmd{xmPushButton}}
    \label{class:xmPushButton}
    \indexeditem{xmpushbutton}{\cmd{xmPushButton}}
        The regular button, displaying a text or pixmap label,
        surrounded by a beveled shadow. When focus is gained,
        the button appear brighter, if it is sensitive.
            \window{button_push}
        Pressing the mouse change the shadow to make the
        impression that the button ase been pushed in, when
        mouse is released, the button appear normal.
        The default push buttons of a dialog may be specified
        by \cmd{-showAsDefault true}, in which case an
        additional border is drawn using the margin
        resources.
    \index{arrow@Arrow|see \cmd{xmArrowButton}}
    \indexeditem{xmarrowbutton}{\cmd{xmArrowButton}}
        A button showing an arrow, whose direction is given by
        the \cmd{-arrow\linebreak[0]Direction} resource.
            \window{button_arrow}
    \index{toggle button@Toggle button|see \cmd{xmToggleButton}}
    \index{radio button@Radio button|see \cmd{xmToggleButton}}
    \index{choice@Choice|see \cmd{xmToggleButton}}
    \indexeditem{xmtogglebutton}{\cmd{xmToggleButton}}
        A button, which displays a state in an on/off
        indicator.  Usually, a toggle button consist of a
        square or diamond indicator with an associated label.
            \window{button_toggle}
        An empty or filled indicator, or a different pixmap may
        be used to indicates the selected/unselected state of
        the button.
        A set of ``radio buttons'' might be grouped into a
        manager (see section~\ref{sec:managers}), with the
        \cmd{-radioBehavior} set to \cmd{True}, to ensure that
        only one of them will be selected at a given time.  If
        the manager's \cmd{-radioAlwaysOne} resource is also
        set, then there will alway be exactly one toggle button
        set.
\end{description}
\subsubsection*{Resources}
Button resources are~:
\begin{rsrctable}{xmPushButton}
  \idx{-armColor}                        &   computed    & \sym{Color}        \\
  \idx{-armPixmap}                        &  \sym{none}    & \sym{Pixmap}        \\
  \idx{-defaultButtonShadowThickness}    &    \cmd{0}        & \sym{Dimension}    \\
  \idx{-fillOnArm}                        &  \cmd{True}    & \sym{Boolean}        \\
  \idx{-multiClick}                        &                & \idy{multiclick\_discard} \\
                                        &                & \idy{multiclick\_keep}    \\
  \idx{-showAsDefault}                    &    \cmd{0}        & \sym{Dimension}    \\
\end{rsrctable}
\begin{rsrctable}{xmArrowButton}
  \idx{-arrowDirection}                    & \cmd{arrow\_up}& \idy{arrow\_up}    \\
                                          &                & \idy{arrow\_down}    \\
                                        &                & \idy{arrow\_left}    \\
                                        &                & \idy{arrow\_right}    \\
\end{rsrctable}
\begin{rsrctable}{xmToggleButton}
  \idx{-fillOnSelect}                    & \cmd{True}    & \sym{Boolean} \\
  \idx{-indicatorOn}                    & \cmd{True}    & \sym{Boolean} \\
  \idx{-indicatorSize}                    &  \sym{none}    & \sym{Dimension} \\
  \idx{-indicatorType}                    &\cmd{n\_of\_many}& \idy{n\_of\_many} \\
                                          &                 & \idy{one\_of\_many} \\
  \idx{-selectColor}                    &     computed    & \sym{Color} \\
  \idx{-selectInsensitivePixmap}         & \sym{none}    & \sym{Pixmap} \\
  \idx{-selectPixmap}                    & \sym{none}    & \sym{Pixmap} \\
  \idx{-set}                            & \sym{False}    & \sym{Boolean} \\
  \idx{-spacing}                        &    \cmd{4}        & \sym{Dimension} \\
  \idx{-visibleWhenOff}                    &   computed    & \sym{Boolean} \\
\end{rsrctable}
Furthermore, text widgets inherit any resources defined in the
Core (page~\pageref{rsrc:Core}),
Primitive (page~\pageref{rsrc:Primitive}),
and Label (page~\pageref{rsrc:xmLabel}) classes.
\begin{center}\begin{tabular}{lc|lc}
    \cmd{-accelerators}            & (Core)    &
    \cmd{-allignment}            & (Label)    \\
    \cmd{-backgroundPixmap}        & (Core)    &
    \cmd{-background}            & (Core)    \\
    \cmd{-borderColor}            & (Core)    &
    \cmd{-borderWidth}            & (Core)    \\
    \cmd{-bottomShadowColor}    & (Primitive)    &
    \cmd{-bottomShadowPixmap}    & (Primitive)    \\
    \cmd{-fontList}                & (Label)    &
    \cmd{-foreground}            & (Primitive)    \\
    \cmd{-heigth}                & (Core)    &
    \cmd{-highlightColor}        & (Primitive)    \\
    \cmd{-highlightOnEnter}        & (Primitive)    &
    \cmd{-highlightPixmap}        & (Primitive)    \\
    \cmd{-highlightThickness}    & (Primitive)    &
    \cmd{-labelPixmap}            & (Label)    \\
    \cmd{-labelString}            & (Label)    &
    \cmd{-labelType}            & (Label)    \\
    \cmd{-mappedWhenManaged}    & (Core)    &
    \cmd{-marginBottom}            & (Label)    \\
    \cmd{-marginHeight}            & (Label)    &
    \cmd{-marginLeft}            & (Label)    \\
    \cmd{-marginRight}            & (Label)    &
    \cmd{-marginRight}            & (Label)    \\
    \cmd{-marginTop}            & (Label)    &
    \cmd{-navigationType}        & (Primitive)    \\
    \cmd{-recomputeSize}        & (Label)    &
    \cmd{-sensitive}            & (Core)    \\
    \cmd{-shadowThickness}        & (Primitive)    &
    \cmd{-stringDirection}        & (Label)    \\
    \cmd{-topShadowColor}        & (Primitive)    &
    \cmd{-topShadowPixmap}        & (Primitive)    \\
    \cmd{-translations}            & (Core)    &
    \cmd{-traversalOn}            & (Primitive)    \\
    \cmd{-unitType}                & (Primitive)    &
    \cmd{-width}                & (Core)    \\
    \cmd{-x}                    & (Core)    &
    \cmd{-y}                    & (Core)    \\
\end{tabular}\end{center}
\subsubsection*{Callbacks}
In addition to the usual \cmd{helpCallback} and \cmd{destroyCallback},
button widgets define the following new ones~:
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                    Method name    & Why \\
\hline %------------------------------------------------------------------
               \idx{armCallback}    & Button pressed. \\
         \idx{disarmCallback}    & Button released, when the pointer still on it. \\
       \idx{activateCallback}    & Some event triger the Activate function. \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
The toggle button also define the \cmd{\%set} callback substitution,
which is replaced by the boolean state of the button.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%------------------------
\subsection{Decorativ widgets}
\titles{Decorativ widgets}
\index{xmframe@\cmd{xmFrame}}
\index{box@Box |see \cmd{xmFrame}}
\index{xmseparator@\cmd{xmSeparator}}
Simple decorativ widgets include \idx{xmFrame} and \idx{xmSeparator}.
The former is simply a container widget that display a frame around
its child, using in/out shadowing or etching.
The later is a primitive widget that look like a flat or beveled line~; it
is used t separates items in a display.
This two widget classes do not interact with user input, hence they
do not have actions, callbacks or translations.
New decoration resources are~:
\begin{rsrctable}{xmFrame}
  \idx{-marginWidth}    &    \cmd{0}        &    \sym{Dimension}    \\
  \idx{-marginHeight}    &    \cmd{0}        &    \sym{Dimension}    \\
  \idx{-shadowType}        &    dynamic        &   \idy{shadow\_in}    \\
                        &                &   \idy{shadow\_out}    \\
                        &                &    \idy{shadow\_etched\_in}\\
                        &                &    \idy{shadow\_etched\_out}\\
\end{rsrctable}
\begin{rsrctable}{xmSeparator}
  \idx{-margin}            &    \cmd{0}        &    \sym{Dimension}    \\
  \idx{-orientation}    &\cmd{horizontal}
                                          &    \idy{horizontal}    \\
                        &                &    \idy{vertical}    \\
  \idx{-separatorType}    & \cmd{shadow\_etched\_in}
                                          &    \idy{shadow\_etched\_in} \\
                        &                &    \idy{shadow\_etched\_out}\\
                        &                &    \idy{no\_line}        \\
                        &                &    \idy{single\_line}    \\
                        &                &    \idy{double\_line}    \\
                        &                &    \idy{single\_dashed\_line}\\
                        &                &    \idy{double\_dashed\_line}\\
\end{rsrctable}
In addition, they inherit the following resources from the
Primitive (page~\pageref{rsrc:Primitive}),
and Core classes (page~\pageref{rsrc:Core})~:
\begin{center}\begin{tabular}{lc|lc}
    \cmd{-backgroundPixmap}        & (Core)    \\
    \cmd{-background}            & (Core)    &
    \cmd{-borderColor}            & (Core)    \\
    \cmd{-borderWidth}            & (Core)    &
    \cmd{-bottomShadowColor}    & (Primitive)    \\
    \cmd{-bottomShadowPixmap}    & (Primitive)    &
    \cmd{-foreground}            & (Primitive)    \\
    \cmd{-heigth}                & (Core)    &
    \cmd{-mappedWhenManaged}    & (Core)    \\
    \cmd{-shadowThickness}        & (Primitive)    &
    \cmd{-topShadowColor}        & (Primitive)    \\
    \cmd{-topShadowPixmap}        & (Primitive)    &
    \cmd{-unitType}                & (Primitive)    \\
    \cmd{-width}                & (Core)    &
    \cmd{-x}                    & (Core)    \\
    \cmd{-y}                    & (Core)    &
\end{tabular}\end{center}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%-----------------------------------------------------------------
\subsection{\cmd{xmList}}
\titles{\cmd{xmList}}
\index{xmlist@\cmd{xmList}}
\index{xmscrolledlist@\cmd{xmScrolledList} |see \cmd{xmList}}
\index{item@Item |see \cmd{xmList}}
A list is used to display an ordered set of strings.
Mouse or keyboard intercation permit to select item(s).
\medskip
A \cmd{xmScrolledList} should be used when the number of item may be too
large to display in the alloted space in the interface~: the interface is
automatically changed to display a \cmd{xmScrollBar} (see below) to move
the visible part of the list.
A scrolled list widget \sym{w} is a composite widget that have the
following childrens~:
\begin{center}\begin{tabular}{lll}
    \sym{w}\cmd{.HorScrollBar} & \sym{w}\cmd{.VertScrollBar} & \sym{w}\cmd{.ClipWindow}    \\
\end{tabular}\end{center}
The associated names might be used to directly access them, as in the
following example~:
\begin{tclmode}
    xmScrolledList .list managed
    .list.VertScrollBar setValues -troughColor red
\end{tclmode}
\medskip
Different selection mode exist~:
\begin{description}
    \defx{-selectionPolicy}
    \item[\idy{single\_select}] \dopar
        Only one item may be selected at any time.
        A button click in the list deselect any previous selection,
        and select that item.
        Each time a selection is made,
        \cmd{singleSelectionCallback} is called.
    \item[\idy{multiple\_select}] \dopar
        Shift-clicks may be used to ma\-ke multiple selections.
        \cmd{multiple\-Selection\-Callback} is called each time an
        item is selected or unselected.
    \item[\idy{extended\_select}] \dopar
        Any single mouse click deselect anything, and select the
        current item.
        Any shift-click extend the current selection up to the
        item underbeneath the mouse.
        \noindent
        \cmd{extendedSelectionCallback} is called for each item selection
        or deselection.
    \item[\idy{browse\_select}] \dopar
        Mouse dragging may be used to select a range of items.
        Using shift-cli\-cks or shift-drags, more than one range
        may be selected at a given time.
        \noindent
        \cmd{browseSelectionCallback} is called for each
        newly selected item, once mouse button is released.
        \noindent
        This is the default mode.
\end{description}
In all mode, the \cmd{defaultActionCallback} is called when the
user double-click on an item.
The following methods are provided to manage the selection list~:
\begin{description}
    \indexeditem{additem}{\sym{list} \cmd{addItem} \sym{item} \sym{position}}
        Add the specified \sym{item} (any \Tcl string value) to the
        existing list, at the given \sym{position}.
        If \sym{position} is 1 or greater, the new item will be the
        first one, second one, ...
        If \sym{position} is 0, the insertion is made at the end.
     \indexeditem{additemunselected}{\sym{list} \cmd{addItemUnselected} \sym{item} \sym{position}}
        Normally, if you an item already selected, the second instance
        will also be selected. this method ensure that the newly
        inserted item will not be selected.
    \indexeditem{deleteposition}{\sym{list} \cmd{deletePosition} \sym{position}}
        Delete the item specified by \sym{position}.
        If \sym{position} is 0, the last item is deleted.
    \indexeditem{deleteitem}{\sym{list} \cmd{deleteItem} \sym{item}}
        Delete the first occurence of \sym{item} in the list.
        A warning will occur if the item does not exist.
    \indexeditem{deleteallitems}{\sym{list} \cmd{deleteAllItems}}
        Delete all items in the list.
    \indexeditem{selectposition}{\sym{list} \cmd{selectPosition} \sym{position} \sym{notify}}
        Select the item at the given \sym{po\-si\-tion} in the list.
        If \sym{notify} is \cmd{true}, the corresponding
        callback is called.
    \indexeditem{selectitem}{\sym{list} \cmd{selectItem} \sym{item} \sym{notify}}
        Select the first given item in the list.
        If \sym{notify} is \cmd{true}, the corresponding
        callback is called.
    \indexeditem{deselectitem}{\sym{list} \cmd{deselectItem} \sym{item}}
        Deselect the first given item in the list. If the item is at
        multiple position in the list, only the first occurence is
        deselected (even if it's not the selected one !).
    \indexeditem{deselectposition}{\sym{list} \cmd{deselectPosition} \sym{position}}
        Deselect the item at the given position in the list.
    \indexeditem{itemexists}{\sym{list} \cmd{itemExists} \sym{item}}
        Reply \cmd{true} if the \sym{item} is in the list,
        \cmd{false} if not.
    \indexeditem{itemposition}{\sym{list} \cmd{itemPosition} \sym{item}}
        Return the position in th elist of the given \sym{item},
        or \cmd{0} if it does not exists.
    \indexeditem{positionselected}{\sym{list} \cmd{positionSelected} \sym{position}}
         Reply \cmd{true} if the \sym{position} is currently selected,
         \cmd{false} if not.
    \indexeditem{setitem}{\sym{list} \cmd{setItem} \sym{item}}
        Scroll the list so that the first occurence of \sym{item}
        will be at the top of the currently displayed part of
        the list.
    \indexeditem{setposition}{\sym{list} \cmd{setPosition} \sym{position}}
        Scroll the list so that the \sym{position}'th item
        will be at the top of the currently displayed part of
        the list.
    \indexeditem{setbottomitem}{\sym{list} \cmd{setBottomItem} \sym{item}}
        Scroll the list so that the first occurence of \sym{item}
        will be at the bottom of the currently displayed part of
        the list.
    \indexeditem{setbottomposition}{\sym{list} \cmd{setBottomPosition} \sym{position}}
        Scroll the list so that the \sym{position}'th item
        will be at the bottom of the currently displayed part of
        the list.
\end{description}
\subsubsection*{Resources}
List specific resources are~:
\begin{rsrctable}{xmList}
  \idx{-automaticSelection}        &  \cmd{False}    & \sym{Boolean}    \\
  \idx{-doubleClickInterval}    &  Inherited    & \sym{Integer}    \\
  \idx{-fontList}                &  Inherited    & \sym{Font List} \\
  \idx{-itemCount}                &    computed    & \sym{Integer} \\
  \idx{-items}                    &    \sym{none}    & \sym{String array} \\
  \idx{-listMarginHeight}         &    \cmd{0}        & \sym{Integer}    \\
  \idx{-listMarginWidth}        &    \cmd{0}        & \sym{Integer}    \\
  \idx{-listSizePolicy}\co        & \cmd{variable}& \idy{constant} \\
                                &                 & \idy{resize\_if\_possible} \\
                                &                 & \idy{variable} \\
  \idx{-listSpacing}            &    \cmd{0}        & \sym{Integer}    \\
  \idx{-scrollBarDisplayPolicy} &\cmd{as\_needed}& \idy{as\_needed} \\
                                  &                & \idy{static} \\
  \idx{-selectedItemCount}         &    \cmd{0}        & \sym{Integer} \\
  \idx{-selectedItems}            &   \sym{none}    & \sym{String array} \\
  \idx{-selectionPolicy}        & \cmd{browse\_select}
                                                  & \cmd{browse\_select} \\
                                  &                & \cmd{extended\_select} \\
                                  &                & \cmd{multiple\_select} \\
                                  &                & \cmd{single\_select} \\
  \idx{-stringDirection}        &    Inherited    & \idy{string\_direction\_l\_to\_r} \\
                                  &                & \idy{string\_direction\_r\_to\_l} \\
  \idx{-topItemPosition}        &   \cmd{1}        & \sym{Integer} \\
  \idx{-visibleItemCount}        &    \cmd{1}        & \sym{Integer} \\
\end{rsrctable}
Other resources are derived from the
Core (page~\pageref{rsrc:Core}),
Primitive (page~\pageref{rsrc:Primitive}),
and Label (page~\pageref{rsrc:xmLabel}) classes.
\subsubsection*{Callbacks}
List specific supported callbacks are~:
\begin{center}\begin{tabular}{|l|l|}
    \hline %------------------------------------------------------------------
                    Method name    & Why \\
    \hline %------------------------------------------------------------------
        \idx{defaultActionCallback}    & An item was double-clicked. \\
      \idx{singleSelectionCallback}    & An single item was selected. \\
    \idx{multipleSelectionCallback}    & An item was selected, \\
      \idx{browseSelectionCallback}    & when in the corresponding \\
    \idx{extendedSelectionCallback} & selection mode. \\
    \hline %------------------------------------------------------------------
\end{tabular}\end{center}
The following substitutions are defined for this callbacks~:
\begin{description}
    \item[\idx{\%item}] \dopar
        The currently selected item string.
    \item[\idx{\%item\_length}] \dopar
        The string length of the currently selected item.
    \item[\idx{\%item\_position}] \dopar
        The current item position, \cmd{1} indicating the first one.
    \item[\idx{\%selected\_items}] \dopar
        Valid only in multiple, browse or extended callbacks,
        this substitution returns a comma-separated list of all
        currently selected items.
\end{description}
Care should be take to enclose \cmd{\%item} and \cmd{\%selected\_items}
between braces, to avoid parsing error when item string contain
spaces.
\medskip
In addition, text widgets inherit the standard callbacks from
the Primitive class, namely \cmd{helpCallback}
and \cmd{destroyCallback}.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\cmd{xmScale}}
\titles{\cmd{xmScale}}
\index{xmscale@\cmd{xmScale}}
\index{slider@Slider |see \cmd{xmScale}}
A scale widget display a cursor that can be moved between
a minimal and a maximal value.
        \window{scale}
\subsubsection*{Resources}
The scale widget class define the new resources given below.
\begin{rsrctable}{xmScale}
  \idx{-decimalPoints}            &    \cmd{0}        & \sym{Integer}        \\
  \idx{-fontList}                 & Inherited        & \sym{Font List}    \\
  \idx{-highlightOnEnter}         &  \cmd{False}    & \sym{Boolean}        \\
  \idx{-highlightThickness}     &    \cmd{2}        & \sym{Dimension}    \\
  \idx{-maximum}                &    \cmd{100}    & \sym{Integer}        \\
  \idx{-minimum}                &    \cmd{0}        &\sym{Integer}        \\
  \idx{-orientation}            & \cmd{vertical}& \idy{horizontal}    \\
                                  &                & \idy{vertival}    \\
  \idx{-processsingDirection}    &    computed    & \idy{max\_on\_bottom}\\
                                  &                & \idy{max\_on\_left}    \\
                                  &                & \idy{max\_on\_right}\\
                                  &                & \idy{max\_on\_top}    \\
  \idx{-scaleHeight}            &    \cmd{0}        & \sym{Dimension}    \\
  \idx{-scaleWidth}                &    \cmd{0}        & \sym{Dimension}    \\
  \idx{-scaleMultiple}            & $(max-min)/10$& \sym{Integer}        \\
  \idx{-showValue}                &    \cmd{False}    & \sym{Boolean}        \\
  \idx{-titleString}            &    \cmd{""}    & \sym{String}        \\
  \idx{-value}                    &    \cmd{0}        & \sym{Integer}        \\
\end{rsrctable}
The slider may be moved between the integer \cmd{-minimum} and
\cmd{-maximum}. Fractional values are obtained using the
\cmd{-decimalPoints} resource, to display a decimal point.
The slider size may be set by \cmd{-scaleHeight} and \cmd{-scaleWidth}.
\cmd{-showValue} tells to display a textual readout of the current
value.
\cmd{-scaleMultiple} is used for large slider move (Control-arrow on
the keyboard).
\subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
    \hline %------------------------------------------------------------------
                        Method name    & Why \\
    \hline %------------------------------------------------------------------
       \idx{valueChangedCallback}    & The scale value had changed. \\
               \idx{dragCallback}    & The slider is being dragged. \\
    \hline %------------------------------------------------------------------
\end{tabular}\end{center}
In this callbacks, the \idx{\%value} substitution may be used to
retrieve the current scale position.
In addition, \cmd{xmScale} inherits the usual \idx{helpCallback} from
the Primitive abstract class.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%-----------------------------------------------------------------------
\subsection{\cmd{xmScrollBar}}
\titles{\cmd{xmScrollBar}}
\index{xmscrollbar@\cmd{xmScrollBar}}
The \cmd{xmScrollBar} widget is made to allow moving the current
vue of a widget too large to be displayed at once.
Usually, scroll bars will be part of a \cmd{xmScrolledWidget},
\cmd{xmScrolledText} or \cmd{xmScrolledList} widget.
        \window{scrollbar}
An \cmd{xmScrollBar} may be horizontal or vertical (depending
on \cmd{-orientation}.
\index{slider@Slider |see \cmd{xmScrollBar}}
It is composed of the two arrows, a larger rectangle called the
scroll region, and a smaller one: the slider.
The data is scrolled by clicking either arrow, clicking inside
the scroll region, or dragging the slider.
When the mouse is held down in the scroll region or in either arrow,
the data continues to move at a constant speed.
The following example use two scrollbars to move a target button~:
        \ttinclude{examples/scrollbar.tcl}
\subsubsection*{Resources}
The scroll bar widget class define the new resources given below.
\begin{rsrctable}{xmScrollBar}
      \idx{-increment}                    &    \cmd{1}        & \sym{Integer}        \\
      \idx{-initialDelay}                &    \cmd{250} ms& \sym{Integer}        \\
      \idx{-maximum}                    &    \cmd{100}    & \sym{Integer}        \\
      \idx{-minimum}                    &    \cmd{0}        & \sym{Integer}        \\
      \idx{-orientation}                & \cmd{vertical}& \idy{horizontal}    \\
                                          &                 & \idy{vertical}    \\
      \idx{-pageIncrement}                &  \cmd{10}        & \sym{Integer}        \\
      \idx{-processsingDirection}        &    computed    & \idy{max\_on\_bottom}\\
                                          &                & \idy{max\_on\_left}    \\
                                          &                & \idy{max\_on\_right}\\
                                          &                & \idy{max\_on\_top}    \\
      \idx{-repeatDelay}                &    \cmd{50} ms    & \sym{Integer} \\
      \idx{-showArrows}                    &  \cmd{True}    & \sym{Boolean} \\
      \idx{-sliderSize}                    &    computed    & \sym{Integer} \\
      \idx{-troughColor}                &    computed    & \sym{Color} \\
      \idx{-value}                        &    \cmd{0}        & \sym{Integer} \\
\end{rsrctable}
The \cmd{-value} resource contains the current position of the slider's
begin, between \cmd{-minimum} and $\cmd{maximum} - \cmd{sliderSize}$.
The slider move between \cmd{-minimum} and \cmd{-maximum}, by
\cmd{-increment} steps (clipped at the ends).
Clicking either arrow move by \cmd{-pageIncrement}.
\cmd{-sliderSize} may be used to reflect the portion of the
widget which is currently in the view.
\cmd{-troughColor} is the slider fill color.
Constant speed moving is parametrized by \cmd{-repeatDeleay} and
\cmd{-initialDelay}.
If \cmd{-showArrows} is set to \cmd{False}, the scroll bar
won't have arrows on both sides.
\subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
    \hline %------------------------------------------------------------------
                        Method name    & Why \\
    \hline %------------------------------------------------------------------
          \idx{decrementCallback}    & value was decremented. \\
               \idx{dragCallback}    & The slider is being dragged. \\
          \idx{incrementCallback}    & value was incremented. \\
      \idx{pageDecrementCallback}    & value was decremented by pageIncrement. \\
      \idx{pageIncrementCallback}    & value was incremented by pageIncrement. \\
              \idx{toTopCallback}    & value was reset to minimum. \\
           \idx{toBottomCallback}    & value was reset to maximum. \\
       \idx{valueChangedCallback}    & The value had changed. \\
    \hline %------------------------------------------------------------------
\end{tabular}\end{center}
In the corresponding callbacks, the \idx{\%value} substitution will
return the current scroll bar position.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%------------------------------------------------------------------------
\section{Manager widgets}
\label{sec:managers}
\titles{Managers}
Manager widgets are used to layout several widgets together,
enabling to construct complex interfaces from simpler widgets.
Theyre main purpose is to find a suitable geometry that enclose
all managed children ; at creation time,
when the user manually resize the window,
or when widgets dynamically change itself.
Normaly, manager do not interact with events, they just forward them to
to appropriate child.
The notable exception is navigation~: use of keyboard to change
the currently selected children widget.
%--------------------------------------------------
\subsection{The \cmd{xmManager} abstract class}
\label{sec:manager}
\titles{\cmd{xmManager}}
\index{xmmanager@\cmd{xmManager}}
This class is not a subclass of Primitive, but have some
graphical representation, so we have a subset of Primitive's
resources and behavior here.
\subsubsection*{Resources}
The \Motif\ Manager abstract widget class is used to define the
common resource set described below.
\begin{rsrctable}{xmManager}
      \idx{-bottomShadowColor}            &                & \sym{Color}    \\
      \idx{-bottomShadowPixmap}            &  \sym{none}    & \sym{Pixmap}    \\
      \idx{-foreground}                    &  computed        & \sym{Color}    \\
      \idx{-highlightColor}                &  computed        & \sym{Color}    \\
      \idx{-highlightPixmap}            &  \sym{none}    & \sym{Pixmap}    \\
      \idx{-navigationType}                &\cmd{tab\_group}& \idy{none} \\
                                          &                & \idy{tab\_group} \\
                                          &                & \idy{sticky\_tab\_group} \\
                                          &                & \idy{exclusive\_tab\_group} \\
      \idx{-shadowThickness}            &   \cmd{0}        & \sym{Dimension}    \\
      \idx{-stringDirection}            &    Inherited    & \idy{string\_direction\_l\_to\_r} \\
                                          &                & \idy{string\_direction\_r\_to\_l} \\
      \idx{-topShadowColor}                &   computed    & \sym{Color} \\
      \idx{-topShadowPixmap}            &  \sym{none}    & \sym{Pixmap} \\
      \idx{-traversalOn}                &  \cmd{True}    & \sym{Boolean} \\
      \idx{-unitType}                    &  Inherited or \cmd{pixels}
                                                          & \idy{pixels} \\
                                          &                & \idy{100th\_millimeters} \\
                                          &                & \idy{1000th\_inches} \\
                                          &                & \idy{100th\_points} \\
                                          &                & \idy{100th\_font\_units} \\
\end{rsrctable}
\subsubsection*{Callbacks}
The Manager abstract class also defines callbacks for all
manager subclass, descibed in the table below.
\begin{center}\begin{tabular}{|l|l|}
    \hline %------------------------------------------------------------------
                    Method name    & Why \\
    \hline %------------------------------------------------------------------
          \idx{focusCallback}    & The widget will receive input focus. \\
          \idx{helpCallback}    & The usual Help callback. \\
            \idx{mapCallback}    & The widget is mapped on screen. \\
          \idx{unmapCallback}    & The widget is unmapped from screen. \\
    \hline %------------------------------------------------------------------
\end{tabular}\end{center}
There is no special substitution associated with this callbacks.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%--------------------------------------------------
\subsection{\cmd{xmBulletinBoard}}
\titles{\cmd{xmBulletinBoard}}
\index{xmbulletinboard@\cmd{xmBulletinBoard}}
The \cmd{xmBulletinBoard} manager is the simplest one.
Children widgets are positionned using their \cmd{-x}
and \cmd{-y} resources.
There is no particular management when the widget is resized.
\subsubsection*{Resources}
\begin{rsrctable}{xmBulletinBoard}
  \idx{-allowOverlap}                &    \cmd{True}    & \sym{Boolean} \\
  \idx{-autoUnmanage}\co            &    \cmd{True}    & \sym{Boolean} \\
  \idx{-buttonFontList}                &  Inherited    & \sym{Font List} \\
  \idx{-cancelbutton}                &   \sym{none}    & \sym{Widget} \\
  \idx{-defaultbutton}                &   \sym{none}    & \sym{Widget} \\
  \idx{-defaultPosition}            &    \cmd{True}    & \sym{Boolean} \\
  \idx{-dialogStyle}                &   computed    & \small \idy{dialog\_system\_modal} \\
                                      &                 & \small \idy{dialog\_primary\_application\_modal} \\
                                      &                 & \small \idy{dialog\_application\_modal} \\
                                      &                 & \small \idy{dialog\_full\_application\_modal} \\
                                      &                 & \small \idy{dialog\_modless} \\
                                      &                 & \small \idy{dialog\_work\_area} \\
  \idx{-dialogTitle}                &  \sym{none}    & \sym{String} \\
  \idx{-labelFontList}                &  Inherited    & \sym{Font List} \\
  \idx{-marginHeight}                &    \cmd{10}    & \sym{Dimension} \\
  \idx{-marginWidth}                &    \cmd{10}    & \sym{Dimension} \\
  \idx{-noResize}                    &    \cmd{False}    & \sym{Boolean} \\
  \idx{-resizePolicy}                & any            & \idy{resize\_any} \\
                                      &                & \idy{resize\_grow} \\
                                      &                & \idy{resize\_none} \\
  \idx{-shadowType}                    & \cmd{shadow\_out}
                                                    & \idy{shadow\_in}    \\
                                    &                & \idy{shadow\_out}    \\
                                    &                & \idy{shadow\_etched\_in}\\
                                    &                & \idy{shadow\_etched\_out}\\
  \idx{-textFontList}                &   Inherited    & \sym{Font List} \\
  \idx{-textTranslations}\cro        &    \cmd{""}    & \sym{String} \\
\end{rsrctable}
When \cmd{-allowOverlap} is set to \cmd{False}, any placement of children
that would result in an overlap will be rejected.
Setting \cmd{-noResize} to \cmd{True} will disable any resize of the
widget, while \cmd{-resizePolicy} may be used to control more what kind
of resize should be allowed.
\pagebreak
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%-----------------------------------------------------------
\subsection{\cmd{xmRowColumn}} \titles{\cmd{xmRowColumn}}
\index{xmrowcolumn@\cmd{xmRowColumn}}
The \cmd{xmBulletinBoard} manager place its children in one or
more columns (or rows).
Different packing styles, main direction and size options  permit to have
aligned or unaligned rows (or columns), as in the following examples~:
\begin{center}
    \small
    \begin{tabular}{ccc}
    \windowdump{rowcol_row}            & \windowdump{rowcol_array}        & \windowdump{rowcol_column} \\
    \cmd{-packing pack\_tight}        & \cmd{-packing pack\_column}    & \cmd{-orientation horizontal} \\
    \cmd{-orientation horizontal}    & \cmd{-numColumns 2}            & \\
    \end{tabular}
\end{center}
\subsubsection*{Resources}
\begin{rsrctable}{xmRowColumn}
  \idx{-adjustLast}                    &    \cmd{True}    & \sym{Boolean}    \\
  \idx{-adjustMargin}                &    \cmd{True}    & \sym{Boolean}    \\
  \idx{-entryAlignment}                & \cmd{alignment\_center}
                                                    & \idy{alignment\_center} \\
                                    &                & \idy{alignment\_beginning} \\
                                    &                & \idy{alignment\_end} \\
  \idx{-entryBorder}                &    \cmd{0}        & \sym{Integer}    \\
  \idx{-entryClass}                    &    dynamic        & \sym{Widget Class}    \\
  \idx{-isAligned}                    &    \cmd{True}    & \sym{Boolean}    \\
  \idx{-isHomogeneous}                &    \cmd{True}    & \sym{Boolean}    \\
  \idx{-labelString}\co                &    \cmd{""}    & \sym{String}    \\
  \idx{-marginHeight}                &    Inherited    & \sym{Dimension}    \\
  \idx{-marginWidth}                &    Inherited    & \sym{Dimension}    \\
  \idx{-menuAccelerator}            &    ?            & \sym{String}    \\
  \idx{-menuHelpWidget}                &  \sym{none}    & \sym{Widget}    \\
  \idx{-menuHistory}                &  \sym{none}    & \sym{Widget}    \\
  \idx{-menuPost}                    &    \cmd{""}    & \sym{String}    \\
  \idx{-mnemonic}                    &  \sym{none}    & \sym{KeySym}    \\
  \idx{-mnemonicCharSet}            & \sym{dynamic}    & \sym{String}    \\
  \idx{-numColumns}                    &    \cmd{1}        & \sym{Integer}    \\
  \idx{-orientation}                &   computed    & \idy{horizontal}    \\
                                      &                 & \idy{vertical}    \\
  \idx{-packing}                    &    computed    & \idy{pack\_column}    \\
                                      &                & \idy{pack\_none}    \\
                                      &                & \idy{pack\_tight}    \\
  \idx{-popupEnabled}                &  \cmd{True}    & \sym{Boolean}    \\
  \idx{-radioAlwaysOne}                &  \cmd{True}    & \sym{Boolean}    \\
  \idx{-radioBehavior}                &  \cmd{False}    & \sym{Boolean}    \\
  \idx{-resizeHeight}                &  \cmd{True}    & \sym{Boolean}    \\
  \idx{-resizeWidth}                &  \cmd{True}    & \sym{Boolean}    \\
  \idx{-rowColumnType}\co            &\cmd{work\_area}& \idy{menu\_bar}    \\
                                      &                & \idy{menu\_option}    \\
                                      &                & \idy{menu\_popup}    \\
                                      &                & \idy{menu\_pulldown}    \\
                                      &                & \idy{work\_area}    \\
  \idx{-spacing}                    & \cmd{3} or \cmd{0}
                                                      & \sym{Dimension}    \\
  \idx{-subMenuId}                    & \sym{none}    & \sym{Widget}    \\
  \idx{-whichButton}                &     computed    & \sym{Integer} \\
\end{rsrctable}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------------------------------------------------
\subsection{\cmd{xmForm}}
\titles{\cmd{xmForm}}
\index{xmform@\cmd{xmForm}}
A form is a manager widget, created to layout widgets
using neighbourhood relationship, such as ``this widget
should be positionned at the left of this one''.
This is quit general, and enable to define widgets that may resize gracefully.
The following exemple gives illustrate this~:
        \window{UserForm}
This constraints are defined in terms of attachment of each side
of children widgets to the form border, to another widget, to
a relative position in the form, or to the initial position
of the child.
When a resizing occurs, children are adjusted according to this
constraints.
\subsubsection*{Resources}
\begin{rsrctable}{xmForm}
  \idx{-fractionBase}            &     \cmd{100}    & \sym{Integer}    \\
  \idx{-horizontalSpacing}        &    \cmd{0}        & \sym{Dimension} \\
  \idx{-rubberPositioning}        &    \cmd{False}    & \sym{Boolean} \\
  \idx{-verticalSpacing}        &    \cmd{0}        & \sym{Dimension} \\
  \index{attachment@\cmd{-}\sym{side}\cmd{Attachment}}
  \index{leftattachment@\cmd{-leftAttachment}}
  \index{rightattachment@\cmd{-rightAttachment}}
  \index{topattachment@\cmd{-topAttachment}}
  \index{bottomattachment@\cmd{-bottomAttachment}}
  \cmd{-}\sym{side}\cmd{Attachment}    & \cmd{attach\_none}
                                                  & \idy{attach\_form} \\
                                  &                & \idy{attach\_none} \\
                                  &                & \idy{attach\_opposite\_form} \\
                                  &                & \idy{attach\_opposite\_widget} \\
                                  &                & \idy{attach\_position} \\
                                  &                & \idy{attach\_self} \\
                                  &                & \idy{attach\_widget} \\
  \index{offset@\cmd{-}\sym{side}\cmd{Offset}}
  \index{leftoffset@\cmd{-leftOffset}}
  \index{rightoffset@\cmd{-rightOffset}}
  \index{topoffset@\cmd{-topOffset}}
  \index{bottomoffset@\cmd{-bottomOffset}}
  \cmd{-}\sym{side}\cmd{Offset}    &     \cmd{0}        & \sym{Integer} \\
  \index{position@\cmd{-}\sym{side}\cmd{Position}}
  \index{leftposition@\cmd{-leftPosition}}
  \index{rightposition@\cmd{-rightPosition}}
  \index{topposition@\cmd{-topPosition}}
  \index{bottomposition@\cmd{-bottomPosition}}
  \cmd{-}\sym{side}\cmd{Position}&     \cmd{0}        & \sym{Integer} \\
  \index{widget@\cmd{-}\sym{side}\cmd{Widget}}
  \index{leftwidget@\cmd{-leftWidget}}
  \index{rightwidget@\cmd{-rightWidget}}
  \index{topwidget@\cmd{-topWidget}}
  \index{bottomwidget@\cmd{-bottomWidget}}
  \cmd{-}\sym{side}\cmd{Widget}    & \sym{none}    & \sym{Widget} \\
\end{rsrctable}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------------------------------------------------
\subsection{\cmd{xmPanedWindow}}
\titles{\cmd{xmPanedWindow}}
\index{xmpannedwindow@\cmd{xmPanedWindow}}
A panned window is a composite widget used to layout several children
vertically, each in its own pane.
Pane sepators have a handle to interactively change the amont of vertical space
given to each children.
    \window{paned_window}
\subsubsection*{Resources}
\begin{rsrctable}{xmPanedWindow}
  \idx{-marginHeight}                &    \cmd{3}        & \sym{Dimension}    \\
  \idx{-marginWidth}                &    \cmd{3}        & \sym{Dimension}    \\
  \idx{-refigureMode}                &    \cmd{True}    & \sym{Boolean}     \\
  \idx{-sahsHeight}                    &    \cmd{10}    & \sym{Dimension}   \\
  \idx{-sashIndent}                    &    \cmd{-10}   & \sym{Dimension}   \\
  \idx{-sashShadowThikness}            & \sym{dynamic}    & \sym{Dimension}   \\
  \idx{-sahsWidth}                    &    \cmd{10}    & \sym{Dimension}   \\
  \idx{-separatorOn}                &    \cmd{True}    & \sym{Boolean}       \\
  \idx{-spacing}                    &    \cmd{8}        & \sym{Dimension}   \\
\end{rsrctable}
\begin{description}
\item[\cmd{-refigureMode}:]
    The children should be reseted to their appropriate positions when
    the paned window is resized.
\end{description}
\begin{center}\begin{tabular}{|l|c|l|}
  \hline%--------------------------------------------------------------------------
  \cmd{xmPanedWindow} Constraint & \\
                    resource name    & default value & type or legal values \\
  \hline%--------------------------------------------------------------------------
  \idx{-allowResize}                &    \cmd{True}    & \sym{Boolean}     \\
  \idx{-paneMaximum}                &    \cmd{1000}    & \sym{Dimension}   \\
  \idx{-paneMimimum}                &    \cmd{1}        & \sym{Dimension}   \\
  \idx{-skipAdjust}                    &    \cmd{False}    & \sym{Boolean}       \\
  \hline%--------------------------------------------------------------------------
\end{tabular}\end{center}
\cmd{-skipAdjust} : The paned window should not automatically resize this
pane.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------------------------------------
\section{Drag and Drop}
\label{sec:dragdrop}
\titles{Drag and Drop}
\index{drag and drop@Drag and Drop}
\index{cut and paste@Cut and Paste|see Drag and Drop}
\index{dragstart@\sym{w} \cmd{dragStart} \sym{rsrc} \sym{value} ...}
\index{dropsiteregister@\sym{w} \cmd{dropSiteRegister} \sym{rsrc} \sym{value} ...}
Drag and drop was introduced into \Motif\ 1.2. It is complicated. We shall
first look at the drop side. A widget has to first register itself as a
drop site, so that when an attempt is made to drop something on it, it will
try to handle it.
This registration is done by the widget method \idx{dropSiteRegister}.
This registration must include \Tcl\ code to be executed
when a drop is attempted, and this is done using the resource \idx{-dropProc}.
The first part of what makes D\&D hard is that you have potentially two
different applications attempting to communicate, one dropping and the
other accepting the drop.
A protocol is needed between these, so that they share a common language.
This is done in registration by saying what types
of protocol are used, and how many there are. This is done using X atoms,
and the major ones are \cmd{COMPOUND\_TEXT}, \cmd{TEXT} and \cmd{STRING}.
Thus registration is done, for example, by
\begin{tclmode}
    .l dropSiteRegister \
        -dropProc {startDrop %dragContext} \
        -numImportTargets 1 \
        -importTargets COMPOUND_TEXT
\end{tclmode}
\index{numimporttargets@\cmd{-numImportTargets}}
\index{importtargets@\cmd{-importTargets}}
This allows \cmd{.l} to be used as a drop site,
accepting \cmd{COMPOUND\_TEXT} only.
Multiple types are allowed, using the Motif list structure of elements
separated by commas as in \cmd{"COMPOUND\_TEXT, TEXT, STRING"}.
When a drop occurs, the procedure \cmd{startDrop} is called,
with one substituted parameter.
This parameter is a \cmd{dragContext}, which is a widget created to
by \Motif\ to handle the drag part of all this. You must include this
parameter, or the next stage doesn't get off the ground.
When a drag actually occurs, \Motif\ creates a \cmd{dragContext} widget.
A drag is started by holding down the middle button in a drag source,
which is discussed later.
The \cmd{dragContext} widget contains information about the drag
source, which is to be matched up against where the drop occurs.
When the drop occurs, by releasing  the middle button,
the \Tcl\ code registered as \cmd{dropProc} is executed.
This should have the \cmd{dragContext} widget as parameter.
This code may try to determine if the drop should go ahead, but more
normally will just act as a channel through to the actual information
transfer.
Still here~? Good~!
The \cmd{dragProc} doesn't actually do the information transfer,
it just determines whether or not it is possible,
and if it is, what protocols should be used, and how.
The drop receiver may decide that it wants something encoded as \cmd{TEXT},
followed by something encoded as \cmd{COMPOUND\_TEXT},
and then by something in \cmd{STRING} format (beats me why, though...).
it signals this by a (\Tcl) list of
dropTransfer pairs, consisting of the protocol (as an X atom name) and the
widget that is being dropped on. Huh? Why the widget that is being dropped
on? Because when a drop on a widget takes place, this is actually dealt
with by the dragContext widget, and this is about to hand the transfer over
to a transferWidget. Yes, I know you are using \Tcl\ because you couldn't
handle triple indirections (or rather, don't want too!), but they occur
anyway... So here is a simple dragProc:
\begin{tclmode}
    proc startDrop {dragContext} {
        $dragContext dropTransferStart \
            -dropTransfers {{COMPOUND_TEXT .l}} \
            -numDropTransfers 1 \
            -transferProc {doTransfer %closure {%value}}
\end{tclmode}
\index{droptransfers@\cmd{-dropTransfers}}
\index{numdroptransfers@\cmd{-numDropTransfers}}
\index{transferproc@\cmd{-transferProc}}
The dragContext widget uses the command \idx{dropTransferStart} to signal
the beginning of the information transfer
(it could also signal that the drop is to terminate, with no
information transfer).  It will accept one chunk of information in the
\cmd{COMPOUND\_TEXT} format, and pass this on to the \cmd{.l} widget.
The information transfer is actually carried on by the Tcl procedure in the
transferProc resource. The only formats currently accepted (because they
are hard-coded into \Tm) are \cmd{COMPOUND\_TEXT}, \cmd{TEXT} and
\cmd{STRING}.
The \cmd{transferProc} resource is a function that is called when the drop
receiver actually gets the information dropped on it. This should take at
least two parameters. The \idx{\%value} is substituted for the actual
information dropped on it, and \idx{\%closure} is the second element in
the dropTransfer list
which should be the widget the drop is happening on.
(Why not let \Tm\ determine this? I dunno. Consistency with \Motif\ doco?
Brain damage late at night?)
Then the dropped on widget can take suitable action. This function
resets the label to the text dropped on it:
\begin{tclmode}
    proc doTransfer {destination value} {
         $destination setValues -labelString $value
\end{tclmode}
\noindent
where destination is substituted by \cmd{\%closure} and value by
\cmd{\%value}.
\vfill\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------------------------------------
\section{Send}
\Tk\ has a primitive called \cmd{send}.
In this, each interpreter has a name, and you can send \Tcl\ commands from
one interpreter to another.
When an interpreter receives a sent command it executes it,
and returns any result back to the original interpreter.
This mechanism is also available to \Tm\, so that Motif applications can
set commands to other Motif applications, and also to and from \Tk\ ones.
If a \Tm\ application succeeds in registering its name,
from then on, it can send to another. For example,
\begin{tclmode}
    send interp2 {puts stdout "hello there"}
\end{tclmode}
instructs ``interp2'' to display a message.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%----------------------------------------------------
\section{More Widgets}
\label{sec:complex}
%-------------------------------------------------
\subsection{\cmd{xmCommand}}
\titles{\cmd{xmCommand}}
\index{xmcommand@\cmd{xmCommand}}
A command widget is composed of an history area (a \cmd{xmScrolledList}),
a label to display the prompt, and a text field to edit the
current command.
The command widget is a sub-class of \cmd{xmSelectionBox}.
You are able to add an extra child, called the work area.
In the example below, this was used to add a button bar~:
        \window{command}
\subsubsection*{Methods}
The command widget recognize a few new methods~:
\begin{description}
\indexeditem{appendvalue}{\sym{cmd} \cmd{appendValue} \sym{command}}
    Append \sym{cmd} to the string already in the text field.  The
    string will be truncated before the first \cmd{\\n} encontered.
\indexeditem{error}{\sym{cmd} \cmd{error} \sym{error\_message}}
    Temporalily display the \sym{error\_message} at the bottom of
    the history area. It will automatically disapear once the
    user entered another command.
\indexeditem{setvalue}{\sym{cmd} \cmd{setValue} \sym{command}}
    Replace the string in the text field by \sym{command}.
    The old command is not entered in the history.
\end{description}
\subsubsection*{Resources}
\begin{rsrctable}{xmCommand}
  \idx{-command}                &    \cmd{""}    & \sym{String} \\
  \idx{-historyItems}            &    \cmd{""}    & \sym{String Table} \\
  \idx{-historyItemCount}        &    \cmd{0}        & \sym{Integer} \\
  \idx{-historyMaxItems}        &    \cmd{100}    & \sym{Integer} \\
  \idx{-historyVisibleItemCount}&   \cmd{8}     & \sym{Integer} \\
  \idx{-promptString}           &   \cmd{">"}   & \sym{String} \\
\end{rsrctable}
Other ones are inherited from \cmd{xmSelectionBox} and its ancestors.
\subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                    Method name    & Why \\
\hline %------------------------------------------------------------------
   \idx{commandChangedCallback}    & The current command changed (you type a key in)\\
   \idx{commandEnteredCallback}    & The command was entered (return key) \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
Both of this callbacks suport the \idx{\%value} and \idx{\%length}
substitution, which are replaced by the string (or string length) that
fired the callback.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%-------------------------------------------------
\subsection{\cmd{xmDrawingArea} and \cmd{xmDrawnButton}}
\label{sec:drawn}
\titles{Drawn widgets}
\index{xmdrawingarea@\cmd{xmDrawingArea}}
\index{xmdrawingbutton@\cmd{xmDrawnButton}}
\index{xlib drawing@\Xlib\ drawing}
\index{getgc@\sym{w} \cmd{getGC} \sym{rsrc} \sym{value} ...}
\Tm\ (version \tmVersion) have a very limited support for \Xlib\ drawable area
or buttons~: you can only draw string on them.
\subsubsection*{Drawing methods}
To manipulate such a widget, the currently defined methods are~:
\begin{description}
    \indexeditem{drawimagestring}{\sym{w} \cmd{drawImageString} \sym{gc} \sym{x} \sym{y} \sym{string}}
        Use the given graphical context \sym{gc} to draw the string \sym{string}
        starting at position \sym{x},\sym{y}.
        The 0,0 coordinate is at the upper-left of the widget.
        For instance, the following code produce an hello widget~:
\begin{tclmode}
    xmDrawingArea .top managed
    .top exposeCallback {
        set gc [.top getGC -foreground black]
        .top drawImageString $gc 10 10 "Hello World"
\end{tclmode}
        Note that it is necessary to use an \cmd{exposeCallback} to get
        the message redisplayed when needed.
\end{description}
\subsubsection*{Resources}
\begin{rsrctable}{xmDrawningArea}
  \idx{-marginHeight}                &    \cmd{10}    & \sym{Dimension}    \\
  \idx{-marginWidth}                &    \cmd{10}    & \sym{Dimension}    \\
  \idx{-resizePolicy}                & \cmd{resize\_any}
                                                      & \idy{resize\_any} \\
                                      &                & \idy{resize\_grow} \\
                                      &                & \idy{resize\_none} \\
\end{rsrctable}
\begin{rsrctable}{xmDrawnButton}
  \idx{-multiClick}                    & Inherited from display
                                                    & \idy{multiclick\_discard} \\
                                    &               & \idy{multiclick\_keep} \\
  \idx{-pushButtonEnabled}            &    \cmd{False}    & \sym{Boolean} \\
  \idx{-shadowType}                    & \cmd{shadow\_out}
                                                      & \idy{shadow\_in}    \\
                                    &                & \idy{shadow\_out}    \\
                                    &                & \idy{shadow\_etched\_in}\\
                                    &                & \idy{shadow\_etched\_out}\\
\end{rsrctable}
\subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                    Method name    & Why \\
\hline %------------------------------------------------------------------
           \idx{exposeCallback}    & The area/button should be redrawn \\
            \idx{inputCallback}    & A keyboard oy mouse event arrived for the area.\\
           \idx{resizeCallback}    & The area/button is resized \\
         \idx{acticateCallback}    & The button was activated \\
              \idx{armCallback}    & The button is squashed \\
           \idx{disarmCallback}    & The button is released \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%------------------------
\subsection{\cmd{xmMainWindow}}
\titles{\cmd{xmMainWindow}}
\index{xmmainwindow@\cmd{xmMainWindow}}
This composit widget is to be used for the main window of an application.
As you add child to it (a \cmd{xmMenuBar}, a \cmd{xmCommandWindow},
a \cmd{xmMessageBox}, a work area, \cmd{xmScrollBar}(s), ...)
it manage them, as you could do manually with a \cmd{xmForm}.
The management of the work area is not imediat~: the main window should
know which of is son is the work area widget before you can manage this
child.
The following example will produce a prototype interface of
a standard application~:
    \ttinclude{examples/main.tcl}
\subsubsection*{Resources}
This widget defines the following resources
(renaming resources of its parents)~:
\begin{rsrctable}{xmMainWindow}
  \idx{-commandWindow}                & \sym{none}    & \sym{Widget} \\
  \idx{-commandWindowLocation}        & above            & \idy{command\_above\_workspace} \\
                                    &                & \idy{command\_below\_workspace} \\
  \idx{-mainWindowMarginHeight}        &    \cmd{0}        & \sym{Dimension}    \\
  \idx{-mainWindowMarginWidth}        &    \cmd{0}        & \sym{Dimension}    \\
  \idx{-menuBar}                    & \sym{none}    & \sym{Widget} \\
  \idx{-messageWindow}                & \sym{none}    & \sym{Widget} \\
  \idx{-showSeparator}                &    \cmd{False}    & \sym{Boolean} \\
\end{rsrctable}
\subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                    Method name    & Why \\
\hline %------------------------------------------------------------------
   \idx{commandChangedCallback}    & You type a key in, recall an history item, ... \\
   \idx{commandEnteredCallback}    & \cmd{<key>Enter}, double-click, ...  \\
               \idx{focusCallback}    & The window get focus. \\
                 \idx{mapCallback}    & The window was mapped on screen. \\
               \idx{unmapCallback}    & The window was unmapped. \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Boxes}
\label{sec:boxes}
Boxes are complex widgets with a work area, and a line of buttons.
They are designed to handle common layout of
several more basic widgets.
Boxes might be used as is, or as building blocks of more
complex interfaces.
They are also often used inside {\em dialog} (standalone windows),
see section~\ref{sec:Dialogs}.
%----------------------------------------------------------
\subsection{\cmd{xmMessageBox}}
\titles{\cmd{xmMessageBox}}
\index{xmmessagebox@\cmd{xmMessageBox}}
Message box are used to display simple messages.
\cmd{xmMessageBox} may also display a symbol (pixmap) to show warnings,
error conditions, ...
This may be done by setting the \cmd{-dialogType} resource, or by
specifying a pixmap (\cmd{-symbolPixmap}), as in the following
example~:
    \window{message}
\medskip
A message box is a composite widget, whose component children might be managed
or unmanaged. This is done using the usual \Tm\ commands \cmd{manageChild} and
\cmd{unmanageChild} applyed on the automatically derived children objects.
If the message box is named \sym{w}, the known childrens are~:
\begin{center}\begin{tabular}{lll}
    \sym{w}\cmd{.Cancel}    & \sym{w}\cmd{.Help}        & \sym{w}\cmd{.Message} \\
    \sym{w}\cmd{.OK}        & \sym{w}\cmd{.Separator}    & \sym{w}\cmd{.Symbol}
\end{tabular}\end{center}
The next example start a \cmd{xmMessageBox}, then drops unwanted features
(buttons and the separator line), then add an icon, and finally manage it.
\begin{tclmode}
    xmMessageBox .message \
        -messageString "Some simple message"
    foreach child {OK Cancel Help Separator} {
        .message.$child unmanageChild
    .message.Symbol setValues -labelPixmap face
    .message manageChild
\end{tclmode}
\subsubsection*{Resources}
\begin{rsrctable}{xmMessageBox}
  \idx{-cancelLabelString}            & \cmd{"Cancel"}    & \sym{String} \\
  \idx{-defaultButtonType}            & \cmd{dialog\_ok\_button}
                                                        & \idy{dialog\_cancel\_button} \\
                                    &                    & \idy{dialog\_help\_button} \\
                                    &                    & \idy{dialog\_ok\_button} \\
  \idx{-dialogType}                    & \cmd{dialog\_message}
                                                        & \idy{dialog\_error} \\
                                    &                    & \idy{dialog\_information} \\
                                    &                    & \idy{dialog\_message} \\
                                    &                    & \idy{dialog\_question} \\
                                    &                    & \idy{dialog\_warning} \\
                                    &                    & \idy{dialog\_working} \\
  \idx{-helpLabelString}            & \cmd{"Help"}        & \sym{String} \\
  \idx{-messageAlignment}            & \cmd{alignment\_beginning}
                                                        & \idy{alignment\_center} \\
                                    &                    & \idy{alignment\_beginning} \\
                                    &                    & \idy{alignment\_end} \\
  \idx{-messageString}                &    \cmd{""}        & \sym{String} \\
  \idx{-minimizeButtons}            &  \cmd{False}        & \sym{Boolean} \\
  \idx{-okLabelString}                &    \cmd{"Ok"}        & \sym{String} \\
  \idx{-symbolPixmap}                & depend of \cmd{-dialogType}
                                                        & \sym{Pixmap} \\
  \hline%---------------------------------------------------------------------
\end{rsrctable}
 \subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                Method name    & Why \\
\hline %------------------------------------------------------------------
       \idx{cancelCallback}    & The cancel button was activated \\
         \idx{helpCallback}    & The help button was activated, or an Help action arise. \\
           \idx{okCallback}    & The ok button was activated \\
           \idx{focusCallback}    & The window get focus. \\
             \idx{mapCallback}    & The window was mapped on screen. \\
           \idx{unmapCallback}    & The window was unmapped. \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
Furthermore, \cmd{xmMessageBox} also inherits \cmd{destroyCallback}
from \cmd{Core}.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%-----------------------------------------------------
\subsection{\cmd{xmSelectionBox}}
\titles{\cmd{xmSelectionBox}}
\label{sec:xmSelectionBox}
\index{xmselectionbox@\cmd{xmSelectionBox}}
\window{select}
A selection box is a composit box designed to ease creation of interfaces
that enable the user to choose one (or several) items from a list.
A selection box has a number of component children,
which may be managed or unmanaged by the application.
These children widgets are often managed or unmanaged
to add or remove elements from a dialog. \Motif\ gives no information about
types of these widgets, so managing and unmanaging are really the only two
operations that you should perform on these widgets.
The corresponding \Tcl\ commands are automatically created when the master
command is created.
If the SelectionBox is named \sym{w}, they are~:
\begin{center}\begin{tabular}{ll}
    \sym{w}\cmd{.Apply}        & \sym{w}\cmd{.OK} \\
    \sym{w}\cmd{.Cancel}    & \sym{w}\cmd{.Selection} \\
    \sym{w}\cmd{.Help}        & \sym{w}\cmd{.Separator} \\
    \sym{w}\cmd{.ItemsList}    & \sym{w}\cmd{.Text} \\
    \sym{w}\cmd{.Items}        & \\
\end{tabular}\end{center}
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                Method name    & Why \\
\hline %------------------------------------------------------------------
      \idx{applyCallback}    & The Apply button is released. \\
     \idx{cancelCallback}    & The Cancel button is released. \\
         \idx{okCallback}    & The Ok button is released. \\
    \idx{noMatchCallback}    & Nothing match the selection expression. \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
The selection box widget also inherits all the callbacks defined in
\cmd{xmList}, and in \cmd{xmText}.
% Selection Box
    \idx{\%length}
    \idx{\%value}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\cmd{xmFileSelectionBox}}
\titles{\cmd{xmFileSelectionBox}}
\label{sec:xmFileSelectionBox}
\index{xmfileselectionbox@\cmd{xmFileSelectionBox}}
\window{fileselect}
The file selection box is designed to let the user interactively specify
a directory and a file.
A filter may be used to display only certain files, based on a regular
expression matching their name.
\begin{center}\begin{tabular}{lll}
    \sym{w}\cmd{.Apply}        & \sym{w}\cmd{.FilterLabel}    & \sym{w}\cmd{.Items}    \\
    \sym{w}\cmd{.Cancel}    & \sym{w}\cmd{.FilterText}    & \sym{w}\cmd{.OK}        \\
    \sym{w}\cmd{.DirList}    & \sym{w}\cmd{.Help}        & \sym{w}\cmd{.Selection} \\
    \sym{w}\cmd{.Dir}        & \sym{w}\cmd{.ItemsList}    & \sym{w}\cmd{.Separator} \\
    \sym{w}\cmd{.Text} \\
\end{tabular}\end{center}
\subsubsection*{Resources}
\begin{rsrctable}{xmFileSelectionBox}
\end{rsrctable}
\subsubsection*{Callbacks}
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                    Method name    & Why \\
\hline %------------------------------------------------------------------
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
% xmFileSelectionBox
    \idx{\%value}
    \idx{\%value\_length}
    \idx{\%mask}
    \idx{\%mask\_length}
    \idx{\%dir}
    \idx{\%dir\_length}
    \idx{\%pattern}
    \idx{\%pattern\_length}
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Menus}
\label{sec:menus}
\titles{Menus}
\index{menus@Menus}
%\window{menus}
Menus are ...
In \Motif, this is done by using separate widgets for all the actors~:
\begin{description}
\item[A \bf menu bar~:]\dopar
    that might be used to group (horizontally by default) several menu
    buttons.
    This will be described in the \cmd{xmMenuBar} section.
\item[\bf menu buttons~:]\dopar
    A special subtype of \cmd{xmPushButton} that automatically popup
    a pulldown menu. When this widget is created as a child of another
    popup menu, (hence in a cascading submenu), a small arrows is added
    at the right of the label.
    This will be described in the \cmd{xmCascadeButton} section.
\item[the \bf pulldown menu~:]
    This a special king of \cmd{xmRowColumn} widget, intented to hold
    several buttons (and separators) vertically.
    This will be described in the next section.
\end{description}
%----------------------------------------------------------
\subsection{\cmd{xmPulldownMenu}}
\titles{\cmd{xmPulldownMenu}}
\index{xmpulldownmenu@\cmd{xmPulldownMenu}}
\index{popup menu@Popup menu |see \cmd{xmPulldownMenu}}
A pulldown menu is a special kind of vertical \cmd{xmRowColumn}.
It is managed only when it should be displayed.
Pulldown or cascading menu are managed when the user clik on some
\cmd{xmCascadeButton}.
Popup menu are managed by a more
general event, typicaly through a defined translation of the main window.
Menu items are child wid\-gets (\cmd{xmLabel}, buttons, \cmd{xmSeparator}, or
\cmd{xm\-Cascade\-Button}).
The order of definition gives the item order.
\begin{center}\begin{tabular}{|l|l|}
\hline %------------------------------------------------------------------
                Method name    & Why \\
\hline %------------------------------------------------------------------
      \idx{popupCallback}    & The menu is managed and mapped. \\
    \idx{popdownCallback}    & The menu is un-mapped. \\
\hline %------------------------------------------------------------------
\end{tabular}\end{center}
%------------------------
\subsection{\cmd{xmCascadeButton}}
\titles{\cmd{xmCascadeButton}}
\index{xmcascadebutton@\cmd{xmCascadeButton}}
The cascade button is a subclass of the usual push button
(\cmd{xmPushButton}, page~\pageref{class:xmPushButton}) that force
management of a pulldown menu.
\begin{rsrctable}{xmCascadeButton}
    \idx{-windowId}        &    \sym{none}    & \sym{Widget} \\
\end{rsrctable}
%------------------------
\subsection{\cmd{xmMenuBar}}
\titles{\cmd{xmMenuBar}}
\index{xmmenubar@\cmd{xmMenuBar}}
A menu bar is an ``ever displayed horizontal pulldown menu'', that may
only contain cascade buttons.
It is used to permanently display the buttons that trigger the pulldown
menus of an application (for instance at the top of a \cmd{xmMainWindow}).
%------------------------
\subsection{Exotic menus}
\titles{Exotic menus}
Examples for a left menu bar, that is always managed
A pulldown menu in a dialog, that start to be displayed at the current setting.
A menu that display icons. (A suitable bushes of push buttons) ?
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%------------------------------------------------------------
\section{Dialogs}
\label{sec:Dialogs}
\titles{dialog widgets}
Dialogs are widgets that appear in their own window on the screen,
when they are managed.
Usually, they are {\em modeless}~:
interactions continue with all visible widgets, while they are visible.
\moat does support the {\em modal} mode through the \idx{dialogStyle}
resource, when set to e.g. \idx{dialog\_full\_application\_modal}.
The modal interaction is exited when the dialog disappear, typically when
the user have activated some push button.
%------------------------
\subsection{Simple informational dialogs}
\index{xmmessagedialog@\cmd{xmMessageDialog}},
\index{xminformationdialog@\cmd{xmInformationDialog}},
\index{xmworkingdialog@\cmd{xmWorkingDialog}},
\index{xmpromptdialog@\cmd{xmPromptDialog}},
\index{xmquestiondialog@\cmd{xmQuestionDialog}},
\index{xmwarningdialog@\cmd{xmWarningDialog}},
\index{xmerrordialog@\cmd{xmErrorDialog}}.
    \window{errorBox}
The simplest dialogs are message boxes in a dialog, with an optional icon.
The predefined icons are~:
\begin{center}
    \begin{tabular}{|c|c|c|}
        \hline
        \windowdump{information} & \windowdump{working} & \windowdump{prompt}  \\
        information & working & prompt  \\
        \hline
        \windowdump{question} & \windowdump{warning} & \windowdump{error}  \\
        question & warning & error  \\
        \hline
    \end{tabular}
\end{center}
\Tm\ defines the following \Tcl\ commands to create this dialogs~:
    \cmd{xmMessageDialog},
     \cmd{xmInformationDialog},
    \cmd{xmWorkingDialog},
    \cmd{xmPromptDialog},
    \cmd{xmQuestionDialog},
    \cmd{xm\-War\-n\-ing\-Dialog},
    \cmd{xmErrorDialog}.
As for the corresponding message boxes, a particular child is accessible
with the specific \Tcl\ command.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{General manager dialogs}
\index{xmformdialog@\cmd{xmFormDialog}}
\index{xmbulletinboarddialog@\cmd{xmBulletinBoardDialog}}
The more general dialogs use the two multi-purpose managers inside.
\moat\ defines the following \cmd{xmFormDialog} and
\cmd{xmBulletinBoardDialog} commands to create them.
%------------------------
\subsection{\cmd{xmSelectionDialog}}
\index{xmselectiondialog@\cmd{xmSelectionDialog}}
This is the standard \Motif\ dialog used to select an item.
See \cmd{xmSelectionBox} (page~\pageref{sec:xmSelectionBox}) for the
corresponding box.
%------------------------
\subsection{\cmd{xmFileSelectionDialog}}
\index{xmfileselectiondialog@\cmd{xmFileSelectionDialog}}
This is the standard \Motif\ dialog used to select a directory and a file
name.
See \cmd{xmFileSelectionBox} (page~\pageref{sec:xmFileSelectionBox}) for the
corresponding box.
\pagebreak %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
{\small
    \titles{Index}
    \label{index}
    \printindex
\tableofcontents
\end{document}